Installation

Install the Woodpecker CLI from npm, verify that it runs, and configure authentication before making API calls. For regular use, the global install is the simplest option because it gives you the short woodpecker command everywhere.

If you cannot install global npm packages on your machine, use npx instead. Both options run the same CLI.

Install

Global install

Install the CLI globally:

npm install -g @woodpecker.co/cli

Then verify the installation:

woodpecker --help
woodpecker --version

If npm fails with a permissions error, your user probably cannot write to the global npm directory. If this is your own development machine and your setup allows it, you can run the install with sudo:

sudo npm install -g @woodpecker.co/cli

On managed machines, CI environments or shared systems, using npx is often the cleaner option.

Run with npx

Use npx when you do not want, or cannot use, a global install:

npx @woodpecker.co/cli --help

When using npx, the command prefix changes. Replace woodpecker with npx @woodpecker.co/cli in examples:

npx @woodpecker.co/cli campaigns list

For one-off checks this is usually enough. For frequent terminal work or scripts, a global install is shorter and easier to read.

Authentication

For local terminal use, store your API key with:

woodpecker login YOUR_API_KEY

You can inspect the active configuration with:

woodpecker config show

For scripts, CI jobs or AI agents, prefer environment variables so secrets stay outside command history and project files:

export WOODPECKER_API_KEY="{YOUR_API_KEY}"
woodpecker campaigns list

If you use npx, the same commands work with the longer prefix:

npx @woodpecker.co/cli login YOUR_API_KEY
npx @woodpecker.co/cli campaigns list

Update

If you installed the CLI globally, run the install command again to update to the latest published version:

npm install -g @woodpecker.co/cli@latest

If you use npx, use the package name with @latest when you explicitly want the newest published version:

npx @woodpecker.co/cli@latest --version

Further reference

For exact Node.js support, all configuration options, environment variables, command flags and shell completion, see the npm package README.