turash/docs/woodpecker-cli-reference.md

Woodpecker CLI Reference

Overview

Woodpecker CLI version: 3.12.0

Current user: SamyRai (gigadamer@gmail.com)

Main Commands

Setup & Configuration

# Initial setup
woodpecker-cli setup [--server URL] [--token TOKEN]

# Show current user info
woodpecker-cli info

# Update CLI to latest version
woodpecker-cli update

Repository Management

# List all repositories
woodpecker-cli repo ls

# Add a repository
woodpecker-cli repo add [options]

# Show repository information
woodpecker-cli repo show [repo]

# Update repository settings
woodpecker-cli repo update [options]

# Remove repository
woodpecker-cli repo rm [repo]

# Synchronize repository list
woodpecker-cli repo sync

# Repair repository webhooks
woodpecker-cli repo repair [repo]

# Assume ownership of a repository
woodpecker-cli repo chown [repo]

Repository Secrets

# List secrets
woodpecker-cli repo secret ls [repo]

# Add a secret
woodpecker-cli repo secret add [options]

# Show secret information
woodpecker-cli repo secret show [repo] [secret]

# Update a secret
woodpecker-cli repo secret update [options]

# Remove a secret
woodpecker-cli repo secret rm [repo] [secret]

Container Registry Management

# List registries
woodpecker-cli repo registry ls [repo]

# Add a registry
woodpecker-cli repo registry add [options]

# Show registry information
woodpecker-cli repo registry show [repo] [registry]

# Update a registry
woodpecker-cli repo registry update [options]

# Remove a registry
woodpecker-cli repo registry rm [repo] [registry]

Pipeline Management

# List pipelines
woodpecker-cli pipeline ls [repo]

# Show latest pipeline
woodpecker-cli pipeline last [repo]

# Show pipeline information
woodpecker-cli pipeline show [repo] [pipeline-number]

# Show pipeline steps
woodpecker-cli pipeline ps [repo] [pipeline-number]

# Show pipeline queue
woodpecker-cli pipeline queue

# Start a pipeline
woodpecker-cli pipeline start [repo] [pipeline-number]

# Stop a pipeline
woodpecker-cli pipeline stop [repo] [pipeline-number]

# Approve a pipeline
woodpecker-cli pipeline approve [repo] [pipeline-number]

# Decline a pipeline
woodpecker-cli pipeline decline [repo] [pipeline-number]

# Trigger deployment pipeline
woodpecker-cli pipeline deploy [repo] [environment]

# Show pipeline logs
woodpecker-cli pipeline log [repo] [pipeline-number] [step-number]

# Purge old pipelines
woodpecker-cli pipeline purge [repo] [options]

Local Pipeline Execution

# Execute pipeline locally
woodpecker-cli exec [path/to/.woodpecker.yaml]

# Common options:
--local                    # Run from local directory
--secrets string=string    # Map of secrets: 'key="value",key2="value2"'
--secrets string           # Path to YAML file with secrets
--backend-engine string    # Backend engine (auto-detect, docker, kubernetes)
--timeout duration         # Pipeline timeout (default: 1h0m0s)
--volumes string           # Pipeline volumes
--network string           # External networks

Pipeline Linting

# Lint pipeline configuration
woodpecker-cli lint [path/to/.woodpecker.yaml]

# Options:
--strict                   # Treat warnings as errors
--plugins-privileged       # Allow privileged plugins

Organization Management

# List organizations
woodpecker-cli org ls

# Show organization
woodpecker-cli org show [org]

# Add organization
woodpecker-cli org add [options]

# Remove organization
woodpecker-cli org rm [org]

Admin Commands

# Manage server settings
woodpecker-cli admin [command]

Global Options

All commands support these global options:

--config string, -c string    # Path to config file [$WOODPECKER_CONFIG]
--server string, -s string    # Server address [$WOODPECKER_SERVER]
--token string, -t string     # Server auth token [$WOODPECKER_TOKEN]
--skip-verify                  # Skip SSL verification [$WOODPECKER_SKIP_VERIFY]
--log-level string             # Set logging level (default: "info")
--pretty                        # Enable pretty-printed debug output
--nocolor                       # Disable colored output

Environment Variables

You can set these environment variables instead of using CLI flags:

• WOODPECKER_SERVER - Server address
• WOODPECKER_TOKEN - Authentication token
• WOODPECKER_CONFIG - Path to config file
• WOODPECKER_SKIP_VERIFY - Skip SSL verification
• WOODPECKER_LOG_LEVEL - Logging level

Common Workflows

1. Setup Repository

# Add repository
woodpecker-cli repo add SamyRai/turash

# Add container registry credentials
woodpecker-cli repo registry add SamyRai/turash \
  --name docker-registry \
  --hostname registry.local \
  --username admin \
  --password secret

# Add secrets
woodpecker-cli repo secret add SamyRai/turash \
  --name DOCKER_USERNAME \
  --value admin

woodpecker-cli repo secret add SamyRai/turash \
  --name DOCKER_PASSWORD \
  --value secret

2. Trigger Pipeline

# Start pipeline manually
woodpecker-cli pipeline start SamyRai/turash

# Trigger deployment
woodpecker-cli pipeline deploy SamyRai/turash production

3. Monitor Pipeline

# Check latest pipeline
woodpecker-cli pipeline last SamyRai/turash

# View pipeline steps
woodpecker-cli pipeline ps SamyRai/turash 123

# View logs
woodpecker-cli pipeline log SamyRai/turash 123 1

4. Test Pipeline Locally

# Lint pipeline
woodpecker-cli lint .woodpecker.yml

# Execute locally
woodpecker-cli exec .woodpecker.yml \
  --local \
  --secrets DOCKER_USERNAME="admin",DOCKER_PASSWORD="secret"

Completion

Generate shell completion:

# Bash
woodpecker-cli completion bash > /etc/bash_completion.d/woodpecker-cli

# Zsh
woodpecker-cli completion zsh > ~/.zsh/completion/_woodpecker-cli

# Fish
woodpecker-cli completion fish > ~/.config/fish/completions/woodpecker-cli.fish