CLI Command Reference

Generated from the command spec — do not edit by hand. Run pnpm gen to refresh.

worca <command> [options]. Every command is built to be driven by a model: result JSON on stdout, progress on stderr, and an exit code you can branch on.

Global flags

• --json — Print a single JSON object to stdout, nothing else
• --wait — Block until the human result is delivered
• --no-wait — Return an id immediately; fetch later with worca tasks get
• --sandbox — Force the local sandbox even if a key is set
• --mock-latency <s> — Sandbox: seconds until a task resolves (default 6)
• --version, -v — Print the version
• --help, -h — Show help (top-level or per-command)

Exit codes

• 0 — delivered
• 20 — rejected / failed
• 1 — usage error
• 2 — auth error

Task types

What a vetted human can do for your agent. Discover these from the CLI with worca tasks types <name>, or over the wire with GET /v1/task-types.

social_post — Social media post

Publish provided content on a social platform. All content comes from the client's AI — the worker executes the steps exactly.

Result: post_url · notes (optional) — proof: url

Example input

{
  "platform": "tiktok",
  "steps": [
    "Log in with the provided account",
    "Create a new post",
    "Upload the video from media_urls",
    "Paste the caption exactly",
    "Publish and copy the URL"
  ],
  "content": "POV: your agent has human hands now 🤝 #ai #automation",
  "media_urls": [
    "https://cdn.example.com/clip-final.mp4"
  ],
  "account_access": "Login via shared 1Password vault item 'Acme TikTok'"
}

video_edit — Video editing

Edit client-provided footage per written instructions — e.g. cut a TikTok short. Source arrives as downloadable links; the edit is returned as a link.

Result: output_url · notes (optional) — proof: url

Example input

{
  "source_urls": [
    "https://drive.google.com/uc?id=raw-demo-footage"
  ],
  "instructions": "Cut to the best 30s. Hook in first 2s. Add auto-captions, trending sound low under VO.",
  "target": "tiktok_short",
  "aspect_ratio": "9:16",
  "max_duration_s": 34
}

phone_call — Phone call

Make a phone call following an exact script and playbook. The worker accomplishes the call and reports a structured outcome.

Result: reached · outcome · summary — proof: structured

Example input

{
  "phone_number": "+14155550123",
  "callee_name": "Jordan (office manager)",
  "objective": "Confirm the appliance delivery window for Thursday",
  "script": "Hi, this is Alex calling on behalf of Acme Logistics about Thursday's delivery...",
  "playbook": "If voicemail: leave callback number. If reschedule requested: offer Fri 9-12 or Mon 1-4.",
  "call_window": "9am-5pm PT"
}

custom — Custom work (quoted)

Describe any task in plain instructions. Worca reviews it and returns a quoted cost; work starts only after the client approves the quote.

Result: summary · output_url (optional) — proof: structured

Example input

{
  "instruction": "Visit the three hardware stores listed and photograph their garden-hose shelf pricing.",
  "deliverable": "One photo per store, legible price tags, uploaded anywhere durable.",
  "links": [
    "https://maps.example.com/store-list"
  ]
}

Commands

worca login

Authenticate with your secret key (prompted, hidden) and get started

worca login [--key wk_live_…] [--url <api-url>]

Flags

• --key wk_live_… — Pass the key non-interactively instead of the hidden prompt
• --url <api-url> — Override the API base URL

Prompts for your secret key (input hidden), validates it against the API, greets you by account name, and points you at worca tasks types. Leave the prompt blank for a local sandbox session. Headless agents skip login entirely and set WORCA_API_KEY in the environment.

worca logout

Forget the stored key and sandbox session

worca logout

worca whoami

Show the current identity (live key or sandbox session)

worca whoami [--json]

worca tasks

Create and track execution tasks

worca tasks <create|get|list|watch|approve|decline|types> [id|type] [options]

Flags

• --type <type> — Task type: social_post · video_edit · phone_call · custom
• --input <@file|json|-> — Task input as a JSON object — @file, inline JSON, or - for stdin
• --deadline <6h|ISO> — Relative (6h, 24h) or ISO timestamp
• --status <status> — Filter for tasks list (queued · awaiting_approval · in_progress · done · failed)

Examples

worca tasks types                       # what tasks can a human do?
worca tasks types phone_call            # field-level docs + example JSON
worca tasks create --type social_post --input @post.json --no-wait --json
worca tasks create --type video_edit --input @edit.json --wait --json
worca tasks get tsk_3b91 --json         # poll the callback ID
worca tasks create --type custom --input @brief.json --no-wait   # quoted first
worca tasks approve tsk_3b91            # accept the quote — work starts
worca tasks decline tsk_3b91            # pass — task closes

create returns the task id — that id is the callback ID your agent polls with tasks get until status is done or failed. custom tasks are quoted first: poll until status is awaiting_approval (quote_cents is set), then tasks approve or tasks decline. Decline exits 0 — a deliberate pass, not a failure.

worca status

Worca system status — queue depth, tasks in progress, pickup ETA

worca status [--json]

Examples

worca status
worca status --json

Live mode reports the platform: the API endpoint in use (so you can tell production from a local override), worker-queue depth, tasks in progress, and the median time until a human picks a task up. Sandbox mode reports the local mock instead. For an uptime check without a key, hit GET /health on the API.

Proof types

screenshot · url · structured · rationale