@kadoa/cli

Official CLI for Kadoa — manage web scraping workflows from the terminal.

Install

npm install -g @kadoa/cli

Or use directly with npx:

npx @kadoa/cli list --json

Quick Start

# Authenticate
kadoa login

# Create a workflow
kadoa create "Extract product names and prices" --url https://example.com/products

# List workflows
kadoa list

# Run a workflow
kadoa run <workflowId>

# Fetch extracted data
kadoa data <workflowId>

Authentication

The CLI resolves your API key in this order:

1. --api-key <key> flag (highest priority)
2. KADOA_API_KEY environment variable
3. ~/.kadoa/config.json (set via kadoa login)

# Interactive login (saves to ~/.kadoa/config.json)
kadoa login

# Or use environment variable
export KADOA_API_KEY=tk-your-key

# Or pass per-command
kadoa list --api-key tk-your-key

Commands

Auth

| Command | Description | |---------|-------------| | kadoa login | Save API key to ~/.kadoa/config.json | | kadoa logout | Remove stored credentials | | kadoa whoami | Show current auth status |

Workflows

| Command | Description | |---------|-------------| | kadoa create <prompt> --url <url> | Create a new workflow | | kadoa list | List all workflows | | kadoa get <id> | Get workflow details | | kadoa run <id> | Run a workflow | | kadoa data <id> | Fetch extracted data | | kadoa approve <id> | Approve and activate a workflow | | kadoa update <id> | Update workflow configuration | | kadoa delete <id> | Delete a workflow | | kadoa completion <shell> | Output shell completion script (zsh, bash) |

Options

# Create
kadoa create "Extract products" \
  --url https://example.com \
  --name "My Workflow" \
  --entity "Product"

# List with filters
kadoa list --state ACTIVE --limit 10

# Fetch data with pagination
kadoa data <id> --limit 50 --page 2 --format csv

# Update
kadoa update <id> --name "New Name" --schedule DAILY

# Delete (with confirmation)
kadoa delete <id>
kadoa delete <id> --force  # skip confirmation

Global Options

| Option | Description | |--------|-------------| | --api-key <key> | Override stored API key | | --json | Force JSON output | | -V, --version | Show version | | -h, --help | Show help |

Output Formats

The CLI auto-detects the best output format:

• Interactive terminal (TTY): Table format
• Piped/redirected: JSON format

Override with --json or --format:

# Force JSON
kadoa list --json

# CSV output
kadoa data <id> --format csv

# Pipe to jq
kadoa list --json | jq '.[].id'

# Save to file
kadoa data <id> --format csv > data.csv

Shell Completions

Tab completion for workflow IDs, subcommands, and flags.

# Zsh (add to ~/.zshrc)
eval "$(kadoa completion zsh)"

# Bash (add to ~/.bashrc)
eval "$(kadoa completion bash)"

Zsh shows workflow names inline: kadoa get <TAB> displays abc123 -- My Workflow.

Completions cache workflow IDs for 60 seconds so repeated tab presses are fast.

CI/CD Usage

# Use env var for auth (no interactive prompts)
export KADOA_API_KEY=${{ secrets.KADOA_API_KEY }}

# Run and fetch data
kadoa run $WORKFLOW_ID --json
kadoa data $WORKFLOW_ID --format csv > output.csv

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Error (API, validation, etc.) | | 2 | Authentication error |

Development

# Install dependencies
bun install

# Run in dev mode
bun src/index.ts list --json

# Build
bun run build

# Test
bun test

# Type check
bun run check-types

License

MIT