Tork CLI

Command-line interface for Tork Governance — authenticate, wire the Tork SDK into your project, and send governed test requests from the terminal.

$ tork test
✔ Governance decision: redact
  receipt: rcpt_01hxyz…
  latency: 214 ms

Install

# npx (no install)
npx @torknetwork/cli --help

# global install
npm install -g @torknetwork/cli

Requires Node.js 20 or newer.

Quickstart

tork login    # 1. authenticate with your tork_ API key
tork init     # 2. install the SDK + write tork.config.json in your project
tork test     # 3. send a synthetic governed request end to end
tork doctor   # 4. verify the whole setup

Commands

All commands support --json for machine-readable output (CI, scripts, AI agents).

tork login

Authenticate the CLI. Prompts for your API key with masked input, validates it live against the API, and stores it in ~/.tork/config.json (created with 600 permissions).

| Flag | Description | | --- | --- | | --key <key> | Provide the key non-interactively (CI, scripts) | | --op <ref> | Read the key from 1Password via op read (e.g. 'op://Vault/Item/field') — requires the 1Password CLI; the resolved key is validated like --key and never printed | | --json | Machine-readable result |

tork init

Set up Tork in the current project. Detects your stack (Node via package.json, Python via requirements.txt/pyproject.toml), flags known AI dependencies (openai, @anthropic-ai/sdk, anthropic, langchain, @langchain/*), asks how you want to govern, installs the matching SDK, prints a runnable snippet, and writes tork.config.json:

• cloud (Node only) — governance via tork.network: real receipts and an audit trail in your dashboard, needs an API key. Installs @torknetwork/sdk.
• local — on-device PII detection and redaction: no API key, works offline, but nothing reaches tork.network so your dashboard stays empty. Installs tork-governance (npm or pip).

Python is local-only today: tork-governance on PyPI runs entirely on-device and never calls the cloud, so --mode cloud with --lang python exits 1 with guidance.

{
  "org_id": "",
  "agent_id": "default-agent",
  "agent_role": "assistant",
  "session_tracking": true,
  "base_url": "https://tork.network"
}

An existing tork.config.json is never overwritten — you get a diff-style notice instead. If both ecosystems are present you are asked which to use; if neither is found the command exits 1 with guidance.

| Flag | Description | | --- | --- | | --lang node\|python | Skip stack detection | | --mode cloud\|local | Skip the governance-mode prompt (CI, scripts) | | --yes, -y | Skip prompts (defaults to Node and cloud mode when unspecified) | | --json | Machine-readable result |

tork test

Send a synthetic governed request through POST /api/v1/govern (fake SSN + fake email — never real data) and print the policy decision, receipt id and round-trip latency. Uses agent_id/agent_role/session_tracking from tork.config.json when present. Exits 0 on any valid governance decision, 1 with a diagnostic otherwise.

| Flag | Description | | --- | --- | | --content "<text>" | Govern custom content instead of the synthetic sample | | --json | Full response, decision and latency as JSON |

tork logs

Show recent governance decisions for your org — time, action (allow green, redact yellow, deny red, escalate magenta), PII count, latency and receipt id. Backed by the receipts feed (GET /api/v1/receipts); entries print oldest-first so the latest decision is at the bottom.

| Flag | Description | | --- | --- | | --limit <n> | Number of decisions to show (default 20) | | --follow | Poll every 5s and print new decisions as they arrive (Ctrl+C to stop; not combinable with --json) | | --json | Machine-readable entries |

tork receipts

List governance receipts, or fetch one by id and verify it:

tork receipts                # list recent receipts
tork receipts tork_rcpt_xxx  # fetch one receipt and verify it

Single-receipt view shows the receipt id, timestamp, action, PII counts, policy version, content hash, fingerprint, governance DNA and whether a signature is present. Verification is honest about what it can do: when the receipt exposes a fingerprint it is checked against the server's merkle anchor via POST /api/v1/verify (✔ verified / ✖ failed, exit 1 on failure); when it doesn't, you get a local structure check only — field presence and hash-format sanity, never claimed as cryptographic verification.

| Flag | Description | | --- | --- | | --limit <n> | Number of receipts to list (default 20) | | --json | Full receipt / verification result as JSON |

tork usage

Show plan usage for the authenticated org from GET /api/v1/usage — plan name, a proportional usage bar, calls used / limit with percentage, calls remaining and the billing period. Warns in yellow at ≥80% of the limit and in red at ≥100%.

| Flag | Description | | --- | --- | | --json | Raw API response plus the normalized summary |

tork doctor

Run all setup checks sequentially and keep going through failures:

1. Config file exists with 600 permissions
2. API key present and format-valid
3. DNS + TLS reachability of the base URL
4. /api/v1/health reports healthy
5. Key accepted by the server
6. tork.config.json present in the current directory (warn only)
7. Tork SDK installed in the project — passes for tork-governance (local mode) or @torknetwork/sdk (cloud mode) and reports which, with version (warn only)
8. Node.js version ≥ 20

Ends with N passed, N warnings, N failed and exits 1 if anything failed.

| Flag | Description | | --- | --- | | --json | {checks: [...], summary: {...}} for CI and AI agents |

tork whoami

Print the active key (masked to tork_****last4), organisation, base URL, and config path. The org is always checked live against the API: on success it shows (verified just now); when the server can't be reached the stored value is printed suffixed (cached — could not verify: <reason>); when the server rejects the key the command additionally exits 1, so scripts never mistake a cached identity for a live one.

Environment variables

| Variable | Effect | | --- | --- | | TORK_API_KEY | Overrides the stored key — nothing is written to disk (ideal for CI) | | TORK_BASE_URL | Overrides the API base URL (default https://tork.network) | | TORK_CONFIG_DIR | Overrides ~/.tork (tests / sandboxes) | | NO_COLOR | Disables colored output |

CI usage

# .github/workflows/governance-check.yml
jobs:
  governance:
    runs-on: ubuntu-latest
    env:
      TORK_API_KEY: ${{ secrets.TORK_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: {node-version: 20}
      - run: npx @torknetwork/cli doctor --json
      - run: npx @torknetwork/cli test --json

Troubleshooting

| Symptom | Likely cause | Fix | | --- | --- | --- | | Invalid key format | Key doesn't start with tork_ | Copy the full key from your Tork dashboard | | Invalid API key: the server rejected… | Key revoked or wrong environment | Generate a new key, run tork login again | | Network error: Could not reach… | Offline, firewall, or bad TORK_BASE_URL | Check connectivity; unset TORK_BASE_URL | | Request … timed out after 10s | Slow network or API incident | Retry; check status via tork doctor | | permissions 644, expected 600 | Config file perms drifted | chmod 600 ~/.tork/config.json | | No Node or Python project detected | Ran tork init outside a project | cd into your project, or use --lang | | SDK check warns not installed | Install failed or skipped | npm install @torknetwork/sdk (cloud) or npm install tork-governance / pip install tork-governance (local) | | Colored output breaks log parsing | ANSI codes in CI logs | Set NO_COLOR=1 or use --json | | 1Password CLI (op) is not installed | --op used without the op CLI | brew install 1password-cli, then op signin | | op read … failed (exit 1) | Bad reference or locked vault | Check the op://Vault/Item/field path; run op signin | | org: … (cached — could not verify) | tork whoami couldn't reach the API or the key was rejected | Check connectivity; if HTTP 401, run tork login again |

Development

npm install
npm run build     # tsc → dist/
npm test          # vitest
npm run coverage  # coverage for src/lib (threshold 80%)
npm link          # try the `tork` binary locally

Built with oclif; future command packs (e.g. tork chat) ship as separate oclif plugins.