Inspect runs and workers with scoped credentials from your terminal.

GetRatchet CLI

@getratchet/cli provides the ratchet executable for Node.js 22+ on Windows, macOS and Linux. It calls the existing API; it does not access PostgreSQL, run handlers or schedule retries.

Install and update

From this repository (the package is not published by this change):

pnpm install
pnpm --filter @getratchet/cli build
pnpm --filter @getratchet/cli exec node dist/bin.js --help
pnpm --filter @getratchet/cli pack --out ./packages/cli/getratchet-cli-0.1.0.tgz
npm install -g ./packages/cli/getratchet-cli-0.1.0.tgz
ratchet --version

Once released to npm, install with npm install -g @getratchet/cli; update with npm install -g @getratchet/cli@latest. Local updates use a freshly built tarball. Uninstall with npm uninstall -g @getratchet/cli.

Credentials and security

Set GETRATCHET_API_KEY through your shell's secure input or CI secret manager. Never put a literal key in shell history or command arguments. ratchet auth login accepts a key from stdin only, for example secret-manager-command | ratchet auth login. It verifies the key and shows at most an eight-character prefix. TTY input is rejected to avoid echoed secrets. Input is bounded to 4096 bytes and 30 seconds.

There is no persistent credential store or native keychain dependency. Login validates only that invocation; it cannot modify the parent shell. Subsequent commands still require GETRATCHET_API_KEY. auth logout reports removed: false, preserves profile configuration and explains how to unset the environment variable. It does not revoke the server key. auth status --json reports source, prefix, profile, origin, scopes and validation state with a nonzero exit on failure.

GET /api/v1/context verifies READ, INGEST, WORKER or administrator credentials and returns organization/scope identifiers and authorized project/environment identifiers. Deploy this endpoint before using login, status, init or doctor with this CLI. Operational reads require READ; publication, synthetic tests, policy changes, replay and cancellation require an administrator key. Existing server billing and replay protections remain authoritative.

HTTPS is mandatory except for exact localhost and 127.0.0.1 origins. URLs cannot contain credentials, paths or queries. HTTP redirects are rejected to prevent credential forwarding. Each request has a 15-second timeout and no automatic retry. After a write times out, inspect server state before repeating it.

Output strips terminal controls and redacts known credentials, authorization headers, token/secret fields, inputs, outputs, ciphertext, provider errors and replay reasons. Run output allowlists public operational fields. Raw provider errors and response bodies are never printed, including in verbose mode. --verbose emits only HTTP method, route family and status to stderr. No ANSI styling is generated; --no-color is accepted everywhere.

Configuration and profiles

Precedence, highest first: command flags → environment variables → current directory's .ratchet.json → selected saved profile → default https://getratchet.app.

Profile selection: --profile → project profile → saved defaultProfile → default. Named profiles must exist in the saved file. The environment credential applies to the selected profile for that invocation; profile names never select persisted secrets.

Create the non-secret config.json manually in:

• Windows: %APPDATA%\GetRatchet (fallback %USERPROFILE%\AppData\Roaming\GetRatchet).
• macOS: ~/Library/Application Support/GetRatchet.
• Linux: $XDG_CONFIG_HOME/getratchet or ~/.config/getratchet.

{
  "schemaVersion": 1,
  "defaultProfile": "dev",
  "profiles": {
    "dev": { "baseUrl": "http://localhost:3000", "projectId": "project-id", "environmentId": "environment-id" }
  }
}

Run ratchet init --project project-id --environment environment-id to verify identifiers through the API and write:

{
  "schemaVersion": 1,
  "profile": "default",
  "baseUrl": "https://getratchet.app",
  "projectId": "project-id",
  "environmentId": "environment-id"
}

Both files reject unknown fields, including secrets. schemaVersion: 1 is required. Defaults may omit project/environment, but effective scope must specify both or neither. IDs use letters, digits, underscores and hyphens, up to 100 characters; profile names up to 64. Configuration is read only from the current directory, without searching parents. Save .ratchet.json in version control when all collaborators share those non-secret identifiers; avoid committing machine-specific profile names. Existing configuration needs explicit confirmation or --force; --yes alone cannot overwrite it. Writes are atomic and interruption does not leave partial configuration.

Commands

ratchet --help
ratchet --version
ratchet auth status --json
ratchet doctor
ratchet tools publish contract.json --dry-run
ratchet tools publish contract.json --yes
ratchet tools test --name echo --contract-version 1 --input-file input.json --yes
ratchet tools test --name echo --contract-version 1 --input '{}' --wait --wait-timeout 120 --yes
ratchet runs list --status FAILED --from 2026-09-01 --limit 20 --json
ratchet runs list --cursor next-page-id --limit 20 --json
ratchet runs show run-id
ratchet jobs cancel job-id --yes
ratchet jobs replay step-id --acknowledge-duplicate-risk --json
ratchet endpoints policy get endpoint-id
ratchet endpoints policy set endpoint-id --file policy.json --dry-run
ratchet endpoints policy set endpoint-id --file policy.json --yes

Synthetic tests require project/environment flags or defaults, name, contract version and exactly one of --input JSON / --input-file. Inputs are at most 64 KiB. Publication accepts JSON and YAML (.yaml/.yml) via the repository's existing YAML parser, without aliases or custom tags. Contract files are at most 256 KiB and share server publication/schema validation. Versions are immutable; publication displays existing versions and confirms before adding a potentially superseding version. Dry-run validates locally and never claims server publication.

Example contract.json:

{
  "name": "echo", "contractVersion": "1", "handlerVersion": "1",
  "description": "Safe echo test", "owner": "platform",
  "inputSchema": { "type": "object" }, "outputSchema": { "type": "object" },
  "replaySafety": "SAFE", "timeoutMs": 30000, "retryPreset": "STANDARD"
}

Synthetic submission and replay responses mean queued, never successful execution. tools test --wait polls read-only run detail at most once a second for 1–3600 seconds (default 60). Output distinguishes QUEUED, RETRY_SCHEDULED, RUNNING, SUCCEEDED, FAILED, CANCELLED, EXHAUSTED and SKIPPED. Only SUCCEEDED returns success after a terminal wait. Timeout or Ctrl+C stops waiting; the server job continues.

Run filters: --q, --run-id, --status (RUNNING/SUCCEEDED/FAILED), --is-test true|false, --service, --tool, --handler-version, --idempotency-key, --from, --to, --limit (1–100), --cursor, plus project/environment. Keep filters identical across cursor pages. JSON retains complete identifiers. Run detail includes steps, attempts, retry state, endpoint and handler version; sensitive inputs/outputs and raw errors are intentionally omitted or redacted.

Cancellation displays the job ID before confirmation. The API has no direct job lookup, so current state is unavailable before the write. CANCEL_REQUESTED is cooperative: a running handler may complete before it sees cancellation. Only CANCELLED is reported as stopped.

Replay always fetches the preview and displays attempt history, eligibility, current versions, compatible upgrade candidates and duplicate-side-effect risk. Interactive sessions must confirm even with --yes or --acknowledge-duplicate-risk. Noninteractive replay requires --acknowledge-duplicate-risk. Version changes additionally require all of:

ratchet jobs replay step-id --acknowledge-duplicate-risk \
  --target-contract-version 2 --expected-handler-version 1 --acknowledge-version-change

--expected-handler-version is the current version from the preview, not the target. Optional --max-attempts is 1–5 (default 1), and --reason is at most 300 characters. There is no additional high-risk override in the current API: FORBIDDEN, dependent, synthetic, active and successful steps remain protected by server eligibility checks.

Example policy.json:

{
  "preset": "CUSTOM", "maxAttempts": 5, "initialDelayMs": 30000,
  "multiplier": 2, "maxDelayMs": 900000, "jitterPercent": 20,
  "defaultTimeoutMs": 30000, "maxConcurrent": 5, "rateLimitPerMinute": null
}

Built-ins: STANDARD, AGGRESSIVE, RELAXED; omit the five custom retry fields for built-ins. Bounds match the shared API schema: attempts 1–10; initial delay 1000–1800000 ms; multiplier 1–4; max delay 1000–86400000 ms and at least initial delay; jitter 0–50%; timeout 100–300000 ms; concurrency 1–100; rate limit null or 1–10000/minute. CLI fetches and sends expectedVersion; an optional file expectedVersion pins an earlier reviewed version. Stale versions fail with exit 5. Before/after is shown before confirmation. Existing jobs retain saved retry policies/timeouts; concurrency and rate limits apply live.

doctor verifies configuration, credential, project/environment, public API/database/queue health and authenticated worker counts. Missing or degraded required checks fail. The API does not expose handler registration versions or worker compatibility; doctor reports this as a warning with remediation. Older servers without /context require an API upgrade.

Automation and output

All commands support --profile, --base-url, --project, --environment, --json, --no-color, --quiet, --verbose, --yes, --help, --version. Command-specific flags are rejected outside their command. Use -- before a filename that starts with a hyphen.

JSON stdout contains one object per invocation: { "schemaVersion": 1, "command": "...", "data": ... }, or { "schemaVersion": 1, "command": "...", "failure": { "message": "...", "exitCode": 2, "status": 400 } }. Auth status, doctor and terminal test failures retain structured diagnostic data with nonzero exit status. Previews and verbose metadata go to stderr. --quiet suppresses normal human output and noninteractive previews, but preserves JSON and errors. No spinners or ANSI codes are used.

CI or redirected stdin/stderr disables prompts. Ordinary writes require --yes; init replacement requires --force; replay requires its own operational acknowledgements. Configure the API key with a CI secret binding, then:

ratchet tools test --name echo --contract-version 1 --input-file fixture.json \
  --project project-id --environment environment-id --wait --yes --json --quiet

Development

pnpm --filter @getratchet/cli test, typecheck, build, and smoke run focused checks. The build bundles the existing pure validators and uses SDK types, without importing the worker/telemetry runtime. The SDK's transport currently retries GETs, disallows query parameters and lacks a cancellation signal; CLI transport therefore uses platform fetch with bounded reads. No SDK behavior is changed.

No database access, local handler execution, durable retry scheduling, persistent credentials, shell completion, deployment automation, plugin system or dashboard is included.