@fieldwork-ai/cli

The Fieldwork CLI: drive your organization's Fieldwork assets and tools from a terminal, a script, or an agent harness like Claude Code.

npm install -g @fieldwork-ai/cli
fieldwork login          # browser sign-in; the token is pinned to the org you pick
fieldwork whoami
fieldwork tool list

Inside a Fieldwork compute container the CLI is preinstalled and pre-authenticated as the conversation's user — no login step; credentials are injected per conversation.

Running tools

Every tool your account can use in chat (platform reads plus your org's connected integrations) is invocable by name. Arguments are one JSON object:

fieldwork tool describe kb_search                 # description + input schema
fieldwork tool run kb_search --args '{"query": "replenishment thresholds"}'
echo '{"database": "Metrics DB", "sql": "select count(*) from orders"}' \
  | fieldwork tool run db_query --args -          # stdin for large payloads
fieldwork tool run kb_search --args '{"query": "x"}' --arg query=override

--arg key=value overlays a string field; --arg key:=json parses the value as JSON. Tool-level errors (strings starting Error:) are data and exit 0; transport and auth failures use the exit codes below.

Asset families

fieldwork agents list | get <slug>
fieldwork kb list | get | search | put <path> | rm | mv | pull --dir <d> | push --dir <d>
fieldwork files list [prefix] | get <path> | put <local> [remote]
fieldwork data list | schema <table> | query "select …"
fieldwork db list | schema <database> [table] | query <database> "select …"
fieldwork apps list | get | init | pull | publish <dir> --message "…"
fieldwork automations list | get | enable | disable | runs [--follow] | run-now [--follow] | logs <name> | delete
fieldwork connectors list | pull <key> | publish <dir> --message "…" | connect <key> --spec <file> | test <id> | secrets set | secrets pull --out <file>

Mutations prompt for confirmation on a TTY; pass --yes to skip (required in non-interactive use). --json prints stable machine-readable output on every verb. Secret values never travel via argv or stdout: secrets set reads from --stdin, --from-env-file, or --from-env; secrets pull writes a chmod-600 file atomically and refuses to overwrite an existing file without --force.

The connector development loop end to end: connectors pull acme_erp → edit the adapter → connectors publish acme_erp --message "…" --base-revision N (a new key creates the definition from the tree's connector.json) → connectors connect acme_erp --spec spec.json → connectors secrets set <id> → automations run-now <sync> --follow to watch the logs.

Auth and configuration

Credential resolution order: the injected container file (~/.fieldwork/credentials) → FIELDWORK_TOKEN / FIELDWORK_API_URL environment variables → the fieldwork login config (~/.config/fieldwork/config.json). One token binds one organization; fieldwork orgs use re-runs the browser flow to switch. Revoke a login anytime in Fieldwork under Settings → Connected apps.

Prefer a native tool surface in an MCP-capable harness? Fieldwork is also a remote MCP server:

claude mcp add --transport http fieldwork https://app.getfieldwork.ai/mcp

Exit codes

0 success (including tool-level Error: strings) · 1 server/network · 2 usage or validation · 3 unauthenticated · 4 forbidden · 5 not found · 6 conflict · 7 rate-limited