Command Line Interface (CLI)

Manage Kadoa workflows from the terminal

The Kadoa CLI offers similar features to the MCP Server — workflow, monitor, notification, variable, template, and change operations available from your terminal, scripts, and CI/CD pipelines. It wraps the Node SDK and runs on Node 18+.

Prerequisites

• A Kadoa account
• The Kadoa CLI installed (see Installation)

Authentication

The CLI authenticates with OAuth. A tk-... API key is not a CLI token. kadoa login opens your browser, signs you in via Kadoa SSO, and stores the access + refresh tokens in ~/.kadoa/config.json (mode 0600). Tokens refresh automatically; you stay logged in until you kadoa logout.

For non-interactive use, provide both KADOA_ACCESS_TOKEN and KADOA_REFRESH_TOKEN so the CLI can refresh the OAuth session.

# Interactive OAuth login
kadoa login

# Sign out (removes ~/.kadoa/config.json)
kadoa logout

Check your current auth status, active team, and role:

kadoa whoami
#   Email: [e-mail]
#   Name:  John Doe
#   Auth:  OAuth (config)
#   Token: valid
#   Active team: Acme Corp [ADMIN]

Quick Start

1. Log in

   Authenticate via your browser — no API key required.

   kadoa login
   
2. Create a workflow

   Describe what to extract in natural language and point it at a URL.

   kadoa create "Extract product names and prices" --url https://sandbox.kadoa.com/ecommerce
   
3. Run it and fetch results

   Trigger a run, then read the extracted data.

   kadoa run <workflowId>
   kadoa data <workflowId>
   
4. Export the dataset

   Stream the full dataset to a file.

   kadoa export <workflowId> --format csv --out products.csv
   

Commands

Global Options

Option	Description
--json	Force JSON output
-V, --version	Show version
-h, --help	Show help

Auth & Team

Command	Description
kadoa login	OAuth login (saves credentials to ~/.kadoa/config.json)
kadoa logout	Remove stored credentials
kadoa whoami	Show current user, team, and role
kadoa team list	List your teams and see which is active
kadoa team switch [team]	Switch active team by name or ID

Workflows

Command	Description
kadoa create <prompt> --url <url>	Create a prompt-driven workflow. Repeat --url for multi-URL workflows on the same domain.
kadoa list	List workflows. Flags: --state <ACTIVE|FAILED|PAUSED|PREVIEW|VALIDATING>, --limit <n>, --format <table|json|csv>
kadoa get <id>	Get workflow details
kadoa run <id>	Run a workflow. --limit <n> caps records.
kadoa pause <id>	Pause an ACTIVE workflow so it stops running on its schedule
kadoa approve <id>	Approve and activate a workflow (also resumes a paused one)
kadoa update <id>	Update workflow config. Flags: --name, --url, --prompt, --schedule, --limit
kadoa delete <id>	Delete a workflow. Use --force to skip the confirmation.

kadoa create accepts the full flag set: --name, --entity, --description, --tag, --limit, --schedule, --cron, plus --notify-email/--notify-webhook/--notify-slack-channel/--notify-websocket to wire notifications at creation time.

The list and get status field shows the computed workflow status, such as Complete, Running, Failed, Paused, or Scheduled. Although the filter flag is named --state, it filters this computed status rather than the API response’s persisted state field.

Data

Command	Description
kadoa data <id>	Paginated read. Flags: --limit <n>, --page <n>, --format <table|json|csv>
kadoa export <id>	Export the full dataset via signed URL. Flags: --format <csv|json>, --out <path>, --run-id <id>, --filters <json>, --sort-by <field>, --order <asc|desc>

export is the right choice for large workflows — it streams the full dataset rather than paginating.

Real-time Monitors

Real-time monitors watch a page and alert on changes. Each detected change is captured in the changes log.

Command	Description
kadoa monitor create [prompt] --url <url>	Create a real-time monitor. At least one --notify-* channel is required.
kadoa changes	List detected changes. Flags: --workflow <id>, --start-date <date>, --end-date <date>, --skip <n>, --limit <n>, --format
kadoa change <changeId>	Show full snapshot and diff for a single detected change

Notifications

Notifications are split into channels (where alerts are delivered: email, webhook, Slack, WebSocket) and settings (which events route to which channels).

Command	Description
kadoa notifications channels list	List channels. --workflow <id> filters to a workflow.
kadoa notifications channels get <id>	Show details for a single channel
kadoa notifications channels create --type <EMAIL|WEBHOOK|SLACK|WEBSOCKET>	Create a channel (see flags below)
kadoa notifications channels delete <id>	Delete a channel. --force skips the prompt.
kadoa notifications settings list	List event-to-channel mappings. --workflow <id>, --event <type> filter.
kadoa notifications settings delete <id>	Delete a setting (channels are kept)
kadoa notifications configure --event <type>	One-step setup: create/reuse a channel and wire it to an event

notifications is aliased as notify. channels create flags depend on --type:

• EMAIL → --recipient <addr> (repeatable; omit for account default), --name <name>
• WEBHOOK → --url <url>, --method <method>, --auth-bearer <token> or --auth-basic <user:pass>
• SLACK → --slack-channel-id <id> or --slack-channel-name <name> (OAuth) or --slack-webhook <url> (legacy)
• WEBSOCKET → no extra flags

configure mirrors the MCP configure_notifications tool — accepts --workflow, repeatable --event (or --event all), and the same --notify-* flags as kadoa create.

Variables

Variables are key/value pairs you reference in workflow prompts as @key.

Command	Description
kadoa vars list	List variables in the active team
kadoa vars get <id>	Show a single variable
kadoa vars create --key <k> --value <v>	Create a variable. --type <STRING|SECRET|OBJECT|ARRAY>
kadoa vars update <id>	Update key, value, or type
kadoa vars delete <id>	Delete a variable. --force skips the prompt.

vars is aliased as variables.

Templates

Templates are reusable, versioned workflow configurations (prompt + schema + notifications).

Command	Description
kadoa templates list	List templates in the active team
kadoa templates get <id>	Show a template with all published versions
kadoa templates create --name <name>	Create an empty template. --description <text>
kadoa templates update <id>	Update name or description
kadoa templates delete <id>	Archive a template (existing workflows are unaffected). --force skips the prompt.
kadoa templates version <id>	Publish a new version. --prompt <text>, --schema-id <id> or --schema-entity <name>
kadoa templates save <workflowId>	Save a workflow as a new template (--name, --description) or as a new version of an existing one (--template-id)
kadoa templates schemas <id>	List schemas associated with a template

Shell Completion

Tab-complete subcommands, flags, and workflow IDs:

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

Output Formatting

The CLI auto-detects the right format: tables in interactive terminals, JSON when piping or redirecting. Override with --json or --format.

kadoa list --json                        # Force JSON
kadoa data <id> --format csv             # CSV output
kadoa list --json | jq '.[].id'          # Pipe to jq
kadoa data <id> --format csv > data.csv  # Save to file

CI/CD

Supply OAuth tokens via environment variables and the CLI runs non-interactively:

# GitHub Actions
env:
  KADOA_ACCESS_TOKEN: ${{ secrets.KADOA_ACCESS_TOKEN }}
  KADOA_REFRESH_TOKEN: ${{ secrets.KADOA_REFRESH_TOKEN }}
steps:
  - run: |
      kadoa run $WORKFLOW_ID --json
      kadoa export $WORKFLOW_ID --format csv --out output.csv

Permissions

The commands you can run depend on your team role. Viewers and Compliance Officers have read-only access — write operations return a 403 with a hint to contact your team admin. The permission matrix matches the MCP Server tool permissions.

Each command also accepts --help for the full flag list, e.g. kadoa create --help.