Initial version of CLI docs (#886)

Signed-off-by: jolheiser <john.olheiser@gmail.com>

Co-authored-by: Anbraten <anton@ju60.de>
This commit is contained in:
John Olheiser 2022-04-19 07:24:24 -05:00 committed by GitHub
parent 67d76248a3
commit 517be0394c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 881 additions and 46 deletions

View file

@ -59,6 +59,10 @@ vendor:
format: format:
@gofmt -s -w ${GOFILES_NOVENDOR} @gofmt -s -w ${GOFILES_NOVENDOR}
.PHONY: docs
docs:
go generate cmd/cli/app.go
.PHONY: clean .PHONY: clean
clean: clean:
go clean -i ./... go clean -i ./...

69
cmd/cli/app.go Normal file
View file

@ -0,0 +1,69 @@
// Copyright 2021 Woodpecker Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package main
import (
"os"
"github.com/rs/zerolog"
zlog "github.com/rs/zerolog/log"
"github.com/urfave/cli/v2"
"github.com/woodpecker-ci/woodpecker/cli/build"
"github.com/woodpecker-ci/woodpecker/cli/common"
"github.com/woodpecker-ci/woodpecker/cli/deploy"
"github.com/woodpecker-ci/woodpecker/cli/exec"
"github.com/woodpecker-ci/woodpecker/cli/info"
"github.com/woodpecker-ci/woodpecker/cli/lint"
"github.com/woodpecker-ci/woodpecker/cli/log"
"github.com/woodpecker-ci/woodpecker/cli/loglevel"
"github.com/woodpecker-ci/woodpecker/cli/registry"
"github.com/woodpecker-ci/woodpecker/cli/repo"
"github.com/woodpecker-ci/woodpecker/cli/secret"
"github.com/woodpecker-ci/woodpecker/cli/user"
"github.com/woodpecker-ci/woodpecker/version"
)
//go:generate go run docs.go app.go
func newApp() *cli.App {
app := cli.NewApp()
app.Name = "woodpecker-cli"
app.Version = version.String()
app.Usage = "command line utility"
app.EnableBashCompletion = true
app.Flags = common.GlobalFlags
app.Commands = []*cli.Command{
build.Command,
log.Command,
deploy.Command,
exec.Command,
info.Command,
registry.Command,
secret.Command,
repo.Command,
user.Command,
lint.Command,
loglevel.Command,
}
zlog.Logger = zlog.Output(
zerolog.ConsoleWriter{
Out: os.Stderr,
},
)
app.Before = common.SetupConsoleLogger
return app
}

64
cmd/cli/docs.go Normal file
View file

@ -0,0 +1,64 @@
// Copyright 2021 Woodpecker Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//go:build generate
// +build generate
package main
import (
"os"
"reflect"
"strings"
"github.com/urfave/cli/v2"
)
func main() {
app := newApp()
for _, cmd := range app.Commands {
fixHiddenFlags(cmd)
}
md, err := app.ToMarkdown()
if err != nil {
panic(err)
}
// Still a bug in our version of urfave/cli/v2
// https://github.com/urfave/cli/pull/1311
md = md[strings.Index(md, "#"):]
fi, err := os.Create("../../docs/docs/40-cli.md")
if err != nil {
panic(err)
}
defer fi.Close()
if _, err := fi.WriteString("# CLI\n\n" + md); err != nil {
panic(err)
}
}
// Until https://github.com/urfave/cli/pull/1346 is merged and tagged
func fixHiddenFlags(cmd *cli.Command) {
var flags []cli.Flag
for _, f := range cmd.Flags {
val := reflect.Indirect(reflect.ValueOf(f)).FieldByName("Hidden")
if !val.IsValid() || !val.Bool() {
flags = append(flags, f)
}
}
cmd.Flags = flags
for _, sub := range cmd.Subcommands {
fixHiddenFlags(sub)
}
}

View file

@ -18,54 +18,12 @@ import (
"os" "os"
_ "github.com/joho/godotenv/autoload" _ "github.com/joho/godotenv/autoload"
"github.com/rs/zerolog" "github.com/rs/zerolog/log"
zlog "github.com/rs/zerolog/log"
"github.com/urfave/cli/v2"
"github.com/woodpecker-ci/woodpecker/cli/build"
"github.com/woodpecker-ci/woodpecker/cli/common"
"github.com/woodpecker-ci/woodpecker/cli/deploy"
"github.com/woodpecker-ci/woodpecker/cli/exec"
"github.com/woodpecker-ci/woodpecker/cli/info"
"github.com/woodpecker-ci/woodpecker/cli/lint"
"github.com/woodpecker-ci/woodpecker/cli/log"
"github.com/woodpecker-ci/woodpecker/cli/loglevel"
"github.com/woodpecker-ci/woodpecker/cli/registry"
"github.com/woodpecker-ci/woodpecker/cli/repo"
"github.com/woodpecker-ci/woodpecker/cli/secret"
"github.com/woodpecker-ci/woodpecker/cli/user"
"github.com/woodpecker-ci/woodpecker/version"
) )
func main() { func main() {
app := cli.NewApp() app := newApp()
app.Name = "woodpecker-cli"
app.Version = version.String()
app.Usage = "command line utility"
app.EnableBashCompletion = true
app.Flags = common.GlobalFlags
app.Commands = []*cli.Command{
build.Command,
log.Command,
deploy.Command,
exec.Command,
info.Command,
registry.Command,
secret.Command,
repo.Command,
user.Command,
lint.Command,
loglevel.Command,
}
zlog.Logger = zlog.Output(
zerolog.ConsoleWriter{
Out: os.Stderr,
},
)
app.Before = common.SetupConsoleLogger
if err := app.Run(os.Args); err != nil { if err := app.Run(os.Args); err != nil {
zlog.Fatal().Err(err).Msg("error running cli") log.Fatal().Err(err).Msg("error running cli")
} }
} }

View file

@ -1,3 +1,743 @@
# CLI # CLI
TODO # NAME
woodpecker-cli - command line utility
# SYNOPSIS
woodpecker-cli
```
[--log-level]=[value]
[--server|-s]=[value]
[--token|-t]=[value]
```
**Usage**:
```
woodpecker-cli [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
```
# GLOBAL OPTIONS
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
# COMMANDS
## build
manage builds
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### ls
show build history
**--branch**="": branch filter
**--event**="": event filter
**--format**="": format output (default: Build #{{ .Number }} 
Status: {{ .Status }}
Event: {{ .Event }}
Commit: {{ .Commit }}
Branch: {{ .Branch }}
Ref: {{ .Ref }}
Author: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}
Message: {{ .Message }}
)
**--limit**="": limit the list size (default: 25)
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--status**="": status filter
**--token, -t**="": server auth token
### last
show latest build details
**--branch**="": branch name (default: master)
**--format**="": format output (default: Number: {{ .Number }}
Status: {{ .Status }}
Event: {{ .Event }}
Commit: {{ .Commit }}
Branch: {{ .Branch }}
Ref: {{ .Ref }}
Message: {{ .Message }}
Author: {{ .Author }}
)
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### logs
show build logs
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### info
show build details
**--format**="": format output (default: Number: {{ .Number }}
Status: {{ .Status }}
Event: {{ .Event }}
Commit: {{ .Commit }}
Branch: {{ .Branch }}
Ref: {{ .Ref }}
Message: {{ .Message }}
Author: {{ .Author }}
)
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### stop
stop a build
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### start
start a build
**--log-level**="": set logging level (default: info)
**--param, -p**="": custom parameters to be injected into the job environment. Format: KEY=value
**--server, -s**="": server address
**--token, -t**="": server auth token
### approve
approve a build
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### decline
decline a build
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### queue
show build queue
**--format**="": format output (default: {{ .FullName }} #{{ .Number }} 
Status: {{ .Status }}
Event: {{ .Event }}
Commit: {{ .Commit }}
Branch: {{ .Branch }}
Ref: {{ .Ref }}
Author: {{ .Author }} {{ if .Email }}<{{.Email}}>{{ end }}
Message: {{ .Message }}
)
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### ps
show build steps
**--format**="": format output (default: Proc #{{ .PID }} 
Step: {{ .Name }}
State: {{ .State }}
)
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
## log
manage logs
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### purge
purge a log
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
## deploy
deploy code
**--branch**="": branch filter (default: master)
**--event**="": event filter (default: push)
**--format**="": format output (default: Number: {{ .Number }}
Status: {{ .Status }}
Commit: {{ .Commit }}
Branch: {{ .Branch }}
Ref: {{ .Ref }}
Message: {{ .Message }}
Author: {{ .Author }}
Target: {{ .Deploy }}
)
**--log-level**="": set logging level (default: info)
**--param, -p**="": custom parameters to be injected into the job environment. Format: KEY=value
**--server, -s**="": server address
**--status**="": status filter (default: success)
**--token, -t**="": server auth token
## exec
execute a local build
**--backend-engine**="": backend engine to run pipelines on (default: auto-detect)
**--build-created**="": (default: 0)
**--build-event**="":
**--build-finished**="": (default: 0)
**--build-link**="":
**--build-number**="": (default: 0)
**--build-started**="": (default: 0)
**--build-status**="":
**--build-target**="":
**--commit-author-avatar**="":
**--commit-author-email**="":
**--commit-author-name**="":
**--commit-branch**="":
**--commit-message**="":
**--commit-ref**="":
**--commit-refspec**="":
**--commit-sha**="":
**--env**="":
**--job-number**="": (default: 0)
**--local**: build from local directory
**--log-level**="": set logging level (default: info)
**--netrc-machine**="":
**--netrc-password**="":
**--netrc-username**="":
**--network**="": external networks
**--parent-build-number**="": (default: 0)
**--prev-build-created**="": (default: 0)
**--prev-build-event**="":
**--prev-build-finished**="": (default: 0)
**--prev-build-link**="":
**--prev-build-number**="": (default: 0)
**--prev-build-started**="": (default: 0)
**--prev-build-status**="":
**--prev-commit-author-avatar**="":
**--prev-commit-author-email**="":
**--prev-commit-author-name**="":
**--prev-commit-branch**="":
**--prev-commit-message**="":
**--prev-commit-ref**="":
**--prev-commit-refspec**="":
**--prev-commit-sha**="":
**--privileged**="": privileged plugins (default: [plugins/docker plugins/gcr plugins/ecr woodpeckerci/plugin-docker woodpeckerci/plugin-docker-buildx])
**--repo-link**="":
**--repo-name**="":
**--repo-private**="":
**--repo-remote-url**="":
**--server, -s**="": server address
**--system-arch**="": (default: linux/amd64)
**--system-link**="": (default: https://github.com/cncd/pipec)
**--system-name**="": (default: pipec)
**--timeout**="": build timeout (default: 1h0m0s)
**--token, -t**="": server auth token
**--volumes**="": build volumes
**--workspace-base**="": (default: /woodpecker)
**--workspace-path**="": (default: src)
## info
show information about the current user
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
## registry
manage registries
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### add
adds a registry
**--hostname**="": registry hostname (default: docker.io)
**--log-level**="": set logging level (default: info)
**--password**="": registry password
**--repository**="": repository name (e.g. octocat/hello-world)
**--server, -s**="": server address
**--token, -t**="": server auth token
**--username**="": registry username
### rm
remove a registry
**--hostname**="": registry hostname (default: docker.io)
**--log-level**="": set logging level (default: info)
**--repository**="": repository name (e.g. octocat/hello-world)
**--server, -s**="": server address
**--token, -t**="": server auth token
### update
update a registry
**--hostname**="": registry hostname (default: docker.io)
**--log-level**="": set logging level (default: info)
**--password**="": registry password
**--repository**="": repository name (e.g. octocat/hello-world)
**--server, -s**="": server address
**--token, -t**="": server auth token
**--username**="": registry username
### info
display registry info
**--hostname**="": registry hostname (default: docker.io)
**--log-level**="": set logging level (default: info)
**--repository**="": repository name (e.g. octocat/hello-world)
**--server, -s**="": server address
**--token, -t**="": server auth token
### ls
list registries
**--log-level**="": set logging level (default: info)
**--repository**="": repository name (e.g. octocat/hello-world)
**--server, -s**="": server address
**--token, -t**="": server auth token
## secret
manage secrets
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### add
adds a secret
**--event**="": secret limited to these events
**--image**="": secret limited to these images
**--log-level**="": set logging level (default: info)
**--name**="": secret name
**--repository**="": repository name (e.g. octocat/hello-world)
**--server, -s**="": server address
**--token, -t**="": server auth token
**--value**="": secret value
### rm
remove a secret
**--log-level**="": set logging level (default: info)
**--name**="": secret name
**--repository**="": repository name (e.g. octocat/hello-world)
**--server, -s**="": server address
**--token, -t**="": server auth token
### update
update a secret
**--event**="": secret limited to these events
**--image**="": secret limited to these images
**--log-level**="": set logging level (default: info)
**--name**="": secret name
**--repository**="": repository name (e.g. octocat/hello-world)
**--server, -s**="": server address
**--token, -t**="": server auth token
**--value**="": secret value
### info
display secret info
**--log-level**="": set logging level (default: info)
**--name**="": secret name
**--repository**="": repository name (e.g. octocat/hello-world)
**--server, -s**="": server address
**--token, -t**="": server auth token
### ls
list secrets
**--log-level**="": set logging level (default: info)
**--repository**="": repository name (e.g. octocat/hello-world)
**--server, -s**="": server address
**--token, -t**="": server auth token
## repo
manage repositories
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### ls
list all repos
**--format**="": format output (default: {{ .FullName }})
**--log-level**="": set logging level (default: info)
**--org**="": filter by organization
**--server, -s**="": server address
**--token, -t**="": server auth token
### info
show repository details
**--format**="": format output (default: Owner: {{ .Owner }}
Repo: {{ .Name }}
Type: {{ .SCMKind }}
Config: {{ .Config }}
Visibility: {{ .Visibility }}
Private: {{ .IsSCMPrivate }}
Trusted: {{ .IsTrusted }}
Gated: {{ .IsGated }}
Remote: {{ .Clone }}
)
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### add
add a repository
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### update
update a repository
**--build-counter**="": repository starting build number (default: 0)
**--config**="": repository configuration path (e.g. .woodpecker.yml)
**--gated**: repository is gated
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--timeout**="": repository timeout (default: 0s)
**--token, -t**="": server auth token
**--trusted**: repository is trusted
**--unsafe**: validate updating the build-counter is unsafe
**--visibility**="": repository visibility
### rm
remove a repository
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### repair
repair repository webhooks
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### chown
assume ownership of a repository
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### sync
synchronize the repository list
**--format**="": format output (default: {{ .FullName }})
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
## user
manage users
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### ls
list all users
**--format**="": format output (default: {{ .Login }})
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### info
show user details
**--format**="": format output (default: User: {{ .Login }}
Email: {{ .Email }})
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### add
adds a user
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
### rm
remove a user
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
## lint
lint a pipeline configuration file
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token
## log-level
get the logging level of the server, or set it with [level]
**--log-level**="": set logging level (default: info)
**--server, -s**="": server address
**--token, -t**="": server auth token