npm package: @kadoa/cli
Description: Kadoa CLI — manage web scraping workflows from the terminal
Latest version: 0.3.0

# @kadoa/cli

Official CLI for [Kadoa](https://kadoa.com) — manage web scraping workflows from the terminal.

## Install

```bash
npm install -g @kadoa/cli
```

Or use directly with npx:

```bash
npx @kadoa/cli list --json
```

## Quick Start

```bash
# 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 (Default)

```bash
kadoa login
```

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

### Email/Password (Headless)

For CI/CD or environments without a browser:

```bash
kadoa login --with-password
```

### Environment Variables (CI/CD)

Export tokens for unattended use:

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

### Logout

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

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

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

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

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

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