@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

Browser Login

kadoa login

This opens your browser to authenticate with Kadoa using Google, email/password, or SSO. Tokens are stored in ~/.kadoa/config.json (mode 0600).

Environment Variables (CI/CD / headless)

Export tokens for unattended use:

export KADOA_ACCESS_TOKEN="<your-token>"
export KADOA_REFRESH_TOKEN="<your-refresh-token>"
kadoa list

Logout

kadoa logout

Tokens are automatically refreshed when they expire.

Commands

Auth & Team

| Command | Description | |---------|-------------| | kadoa login | Log in with Supabase OAuth (browser-based) | | kadoa logout | Remove stored credentials | | kadoa whoami | Show current user, team, and auth status | | kadoa team list | List your teams | | kadoa team switch [team] | Switch active team (by name or ID) |

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 (status shows Complete, Running, Failed, etc.)
kadoa list --state ACTIVE --limit 10
kadoa list --state FAILED

# 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

# Team management
kadoa team list
kadoa team switch "Acme Corp"
kadoa team switch  # interactive picker

Global Options

| Option | Description | |--------|-------------| | --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 vars for auth (no interactive prompts)
export KADOA_ACCESS_TOKEN=${{ secrets.KADOA_ACCESS_TOKEN }}
export KADOA_REFRESH_TOKEN=${{ secrets.KADOA_REFRESH_TOKEN }}

# 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

# Copy build-time env (Supabase project + anon key, same values as kadoa-backend)
cp .env.example .env

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

# Build (inlines values from .env into dist/)
bun run build

# Test
bun test

# Type check
bun run check-types

Releasing

Releases are automated via release-please.

• Use Conventional Commits (feat:, fix:, etc.) on main.
• release-please opens a PR that bumps package.json + appends to CHANGELOG.md based on commits since the last tag.
• Merge the release PR → CI tags + builds + publishes to npm.

No manual npm publish. The build step in .github/workflows/release-please.yml reads NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY from repo secrets and tsup inlines them into dist/index.js. If the Supabase project rotates its anon key, update the repo secret — no code change needed.

License

MIT