From 517be0394c962619e40f53e1833996e09dee836d Mon Sep 17 00:00:00 2001 From: John Olheiser Date: Tue, 19 Apr 2022 07:24:24 -0500 Subject: [PATCH] Initial version of CLI docs (#886) Signed-off-by: jolheiser Co-authored-by: Anbraten --- Makefile | 4 + cmd/cli/app.go | 69 ++++ cmd/cli/docs.go | 64 ++++ cmd/cli/main.go | 48 +-- docs/docs/40-cli.md | 742 +++++++++++++++++++++++++++++++++++++++++++- 5 files changed, 881 insertions(+), 46 deletions(-) create mode 100644 cmd/cli/app.go create mode 100644 cmd/cli/docs.go diff --git a/Makefile b/Makefile index 1a31f5d92..8fe5d9043 100644 --- a/Makefile +++ b/Makefile @@ -59,6 +59,10 @@ vendor: format: @gofmt -s -w ${GOFILES_NOVENDOR} +.PHONY: docs +docs: + go generate cmd/cli/app.go + .PHONY: clean clean: go clean -i ./... diff --git a/cmd/cli/app.go b/cmd/cli/app.go new file mode 100644 index 000000000..2cca06deb --- /dev/null +++ b/cmd/cli/app.go @@ -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 +} diff --git a/cmd/cli/docs.go b/cmd/cli/docs.go new file mode 100644 index 000000000..2e597bfde --- /dev/null +++ b/cmd/cli/docs.go @@ -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) + } +} diff --git a/cmd/cli/main.go b/cmd/cli/main.go index e23277723..36905d36f 100644 --- a/cmd/cli/main.go +++ b/cmd/cli/main.go @@ -18,54 +18,12 @@ import ( "os" _ "github.com/joho/godotenv/autoload" - "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" + "github.com/rs/zerolog/log" ) func main() { - 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 - + app := newApp() if err := app.Run(os.Args); err != nil { - zlog.Fatal().Err(err).Msg("error running cli") + log.Fatal().Err(err).Msg("error running cli") } } diff --git a/docs/docs/40-cli.md b/docs/docs/40-cli.md index 343c5c676..7048b45eb 100644 --- a/docs/docs/40-cli.md +++ b/docs/docs/40-cli.md @@ -1,3 +1,743 @@ # 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