@reduck-ai/cli

Command-line interface for Reduck — run browser automations from your terminal.

Built on top of @reduck-ai/sdk.

Installation

npm install -g @reduck-ai/cli

Authentication

# OAuth login (opens browser)
reduck login

# Or use an API key
export REDUCK_API_KEY=<your-api-key>

Generate an API key from your Reduck dashboard.

Quick start

# Select a device to run automations on
reduck devices

# Run an inline query
reduck run -q "Go to google.com and search for 'reduck ai'"

# Run a typed method with arguments
reduck run --method linkedin.com/get_profile_info --arg username=<linkedin-handle>

# Stream events live as the agent works
reduck run -q "Open example.com" --stream

# Get structured output for scripting
reduck run -q "Open example.com" --output-format json

# Discover what's available
reduck search messaging              # rank sites by host match
reduck get linkedin.com              # show methods + extractor schemas
reduck schema run-result | jq        # JSON Schema for the run result shape

Press Ctrl+C during a run to cancel it gracefully.

Commands

| Command | Description | |---|---| | reduck login | Authenticate via OAuth (opens browser) | | reduck logout | Clear stored credentials | | reduck devices | List and select a device (interactive) | | reduck devices --json | Print devices as JSON (non-interactive) | | reduck devices --set <id> | Save device id as default (non-interactive) | | reduck sessions | Browse recent runs interactively (opens picked one in the web app) | | reduck run | Run an automation (see run options) | | reduck search <query> | Search registered sites by host match | | reduck get <host> | Show registered methods for a site | | reduck interrupt <run-id> | Cancel a running automation | | reduck schema <name> | Print JSON Schema for a CLI output shape |

run options

The run subcommand has two invocation modes (mutually exclusive):

• Inline query: pass -q "..." for a free-form task.
• Typed method: pass --method <host>/<slug> and one or more --arg key=value to invoke a registered method with structured arguments.

| Flag | Alias | Description | |---|---|---| | --query | -q | Free-form task prompt (mutually exclusive with --method) | | --method | — | Invoke a typed method by <host>/<slug> | | --arg | — | Method argument key=value (or key=@/path/to/file). Repeatable. Requires --method | | --attach | — | Local file path to upload (consumable by click_upload). Repeatable | | --paste | — | Paste slot key=value (or key=@/path/to/file). Repeatable. Inserted via paste(slot=...) | | --output-schema | — | Inline vision extractor JSON schema (or @/path/to/schema.json). Mutually exclusive with --method | | --output-format | — | text (default), json, or yaml for the result rendering | | --stream | — | Stream events live as they arrive (default: silent until result) | | --device-id | — | Override default device | | --api-key | — | Override stored credentials |

Only -q has a short alias. All other flags are long-form to avoid -m/-M collisions.

Output modes

The combination of --stream and --output-format controls how events are surfaced:

| | --output-format text (default) | --output-format json | --output-format yaml | |---|---|---|---| | without --stream | silent + human result block at end | one JSON object (the final done) | one YAML doc (the final done) | | with --stream | live human-readable stream | NDJSON (one event per line) | YAML stream (----separated docs) |

For machine-readable shapes, see reduck schema run-event and reduck schema run-result.

The done event

When a run finishes, the final event carries the agent's result alongside any structured data the run produced:

type: done
success: true
output: "Retrieved 3 conversations."   # agent-authored summary string
final_url: "https://www.linkedin.com/messaging/"
extractions:                            # records collected by extractors
  - host: linkedin.com
    slug: get_latest_conversations
    records: [...]
    output_schema: {...}
downloads:                              # files downloaded during the run
  - filename: invoice.pdf
    path: /Users/agent/Downloads/.reduck/abc-123/invoice.pdf
run_id: ...
device_id: ...

Fields final_url, extractions, and downloads are present only when the run produced them. downloads[].path can be reused as --attach in a follow-up run to chain workflows.

In --output-format text, these are rendered as 🌐, 📄, and ⬇ lines below the agent's output.

Saved results

Every reduck run persists the final event (the done event on success, or {success: false, run_id, ...failureEvent} on failure) to ~/.reduck/<run_id>.<ext>:

• .yaml when --output-format yaml, otherwise .json (text falls back to JSON since text is rendering, not serialization).
• Two stderr signals frame the run so stdout stays clean for | jq / | yq piping:
  • → Run result will be saved to ~/.reduck/<run_id>.<ext> (at run start)
  • ✓ Run result saved to ~/.reduck/<run_id>.<ext> (on completion)
• The file content is identical to what stdout produces in json / yaml mode.
• Always-on, no opt-out flag. Failure events (CONNECTION_LOST, agent self-reported failure, etc.) are saved too.

Useful for replays and post-mortem when terminal scroll buffers lose the structured output.

search and get

Both take their main argument positionally:

# Sites whose host matches the query
reduck search messaging
reduck search messaging --json

# All registered methods for a host (with arg schemas + extractor output schemas)
reduck get linkedin.com
reduck get linkedin.com --json

Exit code is 0 iff results are non-empty (search) or the host has registered methods (get).

schema

reduck schema run-result      # JSON Schema (draft-7) of the final `done` event
reduck schema run-event       # JSON Schema of streamed RunEvent (any variant)
reduck schema site
reduck schema method
reduck schema device
reduck schema run-record
reduck schema runs-page

Validate live output with ajv:

reduck run -q "..." --output-format json | ajv -s <(reduck schema run-result)

Configuration

Credentials are stored in ~/.config/reduck/config.json after reduck login. The CLI uses OAuth with PKCE for secure authentication.

Priority order for authentication:

1. --api-key flag
2. REDUCK_API_KEY environment variable
3. Stored OAuth token from reduck login

Priority order for device selection:

1. --device-id flag
2. REDUCK_DEVICE_ID environment variable
3. Device saved via reduck devices

License

MIT