Skip to main content
@rulebase/cli is the Rulebase command line. Beyond the credential helpers (doctor, login, whoami), it exposes the whole work-item API as non-interactive commands that read JSON and print JSON. That makes it the shortest path from a script, a coding agent, or a CI job to the /v1/work_items endpoints, without writing an HTTP client or handling regional hosts yourself.

​
Install and run

The CLI is a zero-dependency Node package. Node 20 or newer is required.
The package installs a single rulebase binary. Prefer the global install on a workstation or an agent image: the command is short, and there is no npm registry round trip on every invocation. In CI, add it as a dev dependency instead, so the version is recorded in your lockfile rather than resolved at job time:
Every example below assumes rulebase is on your PATH. If you would rather not install anything, prefixing any command with npx @rulebase/cli works the same way. rulebase --help lists every command and the exit codes in one screen.

​
Authenticate

Work-item commands authenticate with a Rulebase API key, the same key you would put in an Authorization: Bearer header. Create one in Settings > Connections; see Set up API access for the details.
The OAuth login (rulebase login --region us|eu) exists for MCP tool calls only. REST work-item commands never use it. If whoami shows you are signed in with OAuth but no API key is configured, the work-item commands will still fail with a credentials error.
Two ways to supply the key:
Without RULEBASE_API_KEY, login --auth api-key prompts for the key with the input hidden. The CLI never accepts an API key as a command-line argument, because argv shows up in shell history, ps output, and CI transcripts.

​
Where credentials live, and which one wins

Stored credentials go in ~/.rulebase/credentials.json, in a directory created with mode 0700 and a file written with mode 0600. Override the location with RULEBASE_CREDENTIALS_PATH. Precedence, highest first:
  1. RULEBASE_API_KEY from the environment.
  2. The stored key for the region you passed with --region.
  3. The stored key, when only one region has one.
If keys are stored for both regions and you do not pass --region, the CLI stops rather than guessing, and tells you to pick one.

​
US and EU

Rulebase runs separate US and EU deployments with separate key stores, and a key sent to the wrong region returns exactly the same 401 Unauthorized as a revoked key. The CLI resolves the region for you: it uses --region (or RULEBASE_REGION) when given, the region the key is stored under otherwise, and probes both regions when it has neither.

​
Output contract

Every work-item command writes exactly one JSON object to stdout and nothing else. Progress and warnings go to stderr, never secrets.
Exit codes let a script branch without parsing the body:

​
Commands

All commands take --region us\|eu and read input from a file path or - for stdin.

​
work-items create

Creates a work item from a JSON object. Create-only: a duplicate external_id returns exit code 4 with error.code conflict.

​
work-items get

By Rulebase ID or by your own identifier:

​
work-items list

Newest completion first, cursor paginated:
meta.page.next carries the cursor for the next page and is null on the last one. With --all the CLI walks the pages itself and returns one combined array.

​
work-items update

Patches a stored work item. Omitted fields keep their values, custom_attributes merge with what is stored, and external_id cannot change.

​
work-items delete

Soft-deletes a work item and requires --yes, so no script deletes anything by accident:
The call is idempotent: deleting an already-deleted work item still succeeds and reports "deleted": false.

​
work-items apply

The batch workhorse. Creates, updates, or restores work items by external_id.
The canonical input is the same envelope the API takes:
A bare array is normalized to that envelope, so [{...},{...}] works too. Input is capped at 25 MB. The API accepts 100 items per request; the CLI splits anything larger into chunks of 100 automatically and stitches the responses back together, so index values in the output are positions in your input, in your order:
Item statuses are created, updated, unchanged, restored, or error. If any item fails, the successful items are still applied, the envelope reports "ok": false with error.code partial_failure, the full results array is still present, and the exit code is 1. --dry-run returns the same shape with "dry_run": true and writes nothing.

​
work-items schema

Prints the bundled JSON Schema for the three input shapes, so an agent can validate before sending:
The bundle ships with the package and is checked against the published OpenAPI document on release, so it cannot silently drift from the API.

​
Agent and CI recipes

Reconcile a day of records, failing the job if any item is rejected:
set -e turns the exit code into a failed job: 1 means some items were rejected (inspect /tmp/result.json for the error entries), 3 means the credential is missing or pointed at the wrong region, 4 means the API or the network failed. Pipe a single record straight out of another tool:
Collect every completed work item from a date:

​
JSON apply vs CSV upload

Both write work items; they suit different sources. Use apply from agents and services. Use CSV upload when a human or a legacy system produces a spreadsheet.

​
Behaviour notes

Retries and idempotency. Apply is keyed on external_id, so re-running the same input is safe: items that did not change come back as unchanged. create is not idempotent: the second attempt returns conflict so you find out that you sent the same record twice. The CLI retries 429 and transient network failures a few times with backoff, honouring Retry-After; when it gives up, error.details.retry_after carries the seconds the API asked for. Rate limits. The API allows roughly 5,000 requests per minute per organization. Batching 100 items per request keeps a large backfill comfortably below it. Deletion and restoration. delete is a soft delete: the work item leaves reads and lists and stops being summarized, while evaluations that reference it keep resolving. Applying the same external_id again restores it and reports restored. There is no hard delete and no bulk delete, and items you leave out of an apply are never deleted. Credential safety. Keys are only ever read from the environment or the 0600 credential file, never from argv. Output is redacted: the CLI prints a key family and length (rk_live_…32 chars), never the key.

​
Troubleshooting

unauthorized (exit 3 or 4) that looks like a bad key. Nine times out of ten this is the region. A key issued in EU returns the same 401 against US as a revoked key does. Run:
doctor tries both regions and names the one that accepts your key; then pass --region eu or set RULEBASE_REGION=eu. credentials_ambiguous (exit 3). Keys are stored for both regions. Pass --region. invalid_json or invalid_input (exit 2). The file or stdin did not parse, or an item is missing a required field. Compare against work-items schema; note that completed_at is required whenever status is completed or cancelled. Exit 1 with partial_failure. The request reached the API and most items landed. Look at the entries in data.results whose status is error; their error message names the field at fault. Fix and re-apply; items that already landed come back unchanged.