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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

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

### Organization Management

```bash
# 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

```bash
# Manage server settings
woodpecker-cli admin [command]
```

## Global Options

All commands support these global options:

```bash
--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

```bash
# 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

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

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

### 3. Monitor Pipeline

```bash
# 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

```bash
# 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
# 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
```