woodpecker-cli

woodpecker-cli [global-options] command [command-options] [arguments]

woodpecker-cli is the official command-line client for Woodpecker CI, a container-based continuous integration engine. It talks to a Woodpecker server over its HTTP API (list and trigger pipelines, manage repositories, secrets, registries, and users) and can also compile and run workflow files on the local machine without a server.Workflows live in .woodpecker.yaml, .woodpecker.yml, or a .woodpecker/ directory of YAML files. lint and exec search that default order when no path is given. exec auto-detects a backend (docker, kubernetes, or local); Docker needs a running daemon, while local runs step commands on the host and does not reproduce the container image environment.Server commands need a server URL and an authentication token. woodpecker-cli setup writes a named context and stores the token in the operating-system keyring. Flags and environment variables override stored context values.

-s, --server url

Woodpecker server address. Overrides the current context. Environment: WOODPECKER_SERVER.

Server authentication token. Overrides the keyring entry for the current context. Environment: WOODPECKER_TOKEN. Prefer setup or the environment variable so the token is not visible in process listings.

Path to the legacy `config.json` file. Environment: WOODPECKER_CONFIG. Does not select a named context.

Log level (default info). Environment: WOODPECKER_LOG_LEVEL.

Log destination. stdout and stderr are accepted; default is stderr.

Pretty-print debug output.

Disable color in pretty debug output.

Skip the CLI update check.

Skip TLS verification of the server certificate.

SOCKS proxy for server requests. --socks-proxy-off ignores it.

~/.config/woodpecker/contexts.json

Named contexts on Linux and other Unix systems (`XDGCONFIGHOME` overrides the base). macOS uses `~/Library/Application Support/woodpecker/contexts.json`. Each entry stores name, server_url, and log_level. current_context must name one of those entries. Tokens are not written here; they live in the OS keyring, keyed by server URL.

Legacy single-server file used when no current context can be loaded. Accepts server_url and log_level. --config / WOODPECKER_CONFIG point at this file, not at `contexts.json`.

Default workflow locations, searched in that order by lint and exec.

setup [server]

Create a named context (default default), save the server URL, and store the token in the keyring. If --token is omitted, the CLI opens the Woodpecker UI to issue one. --context / --ctx names the context.

Manage named server contexts: list / ls, use, delete / rm, rename.

Lint workflow YAML. With no path, uses the project's default config. --strict treats warnings as errors.

Compile and run workflows from the local checkout (or --repo-path). --backend-engine selects docker, kubernetes, local, or auto-detect. --env KEY=value sets pipeline environment. --secrets and --secrets-file supply secrets (not downloaded from the server). --pipeline-event, --commit-branch, --commit-sha, --repo, and related flags override CI metadata. --metadata-file replays metadata downloaded from the UI (same CLI/server version only). Default timeout is 1h.

Show the authenticated user.

Manage repositories: ls, show, add, rm, sync, update, chown, repair, plus secret, registry, and cron subcommands. repo ls --all includes inactive repos; --org filters by organization.

Manage pipelines for a repository identified by id or owner/name: ls, show, last, create, start, stop, approve, decline, deploy, ps, queue, purge, and log show / log purge. pipeline ls accepts --branch, --event, --status, --limit (default 25), --before, and --after (RFC3339).

Manage organization secret and registry entries. --organization / --org takes an id or full name.

Server administration: log-level, global secret and registry, user, and org ls. Requires an admin token.

Replace the CLI binary with the latest release. --force reinstalls even when already current.

Server commands fail without a reachable server and a valid token. Tokens in argv appear in process listings and shell history; use setup (keyring) or WOODPECKER_TOKEN.exec --backend-engine docker needs a Docker daemon. local runs commands on the host and does not match container images, users, or packages used on agents.Secrets used by exec must be passed with --secrets or --secrets-file; they are not fetched from the server. Keep local secret files out of version control.--metadata-file is not a stable API. Replay only with the same Woodpecker version that produced the file.Match CLI and server versions. --skip-verify disables TLS verification.The npm package @woodpecker.co/cli is a different product (command name woodpecker). This binary is woodpecker-cli from Woodpecker CI.

Woodpecker CI was forked from Drone 0.8 by @laszlocph in April 2019 after Drone's license change, and renamed Woodpecker in August 2019. The project is Apache 2.0 licensed and remains community-maintained. woodpecker-cli is built from the same Go tree as the server and agent (`cmd/cli`). Current releases are in the 3.x series (3.18 as of August 2026).

docker(1), git(1), act(1), circleci(1), gitea(1)

Source code · Homepage · Documentation