@torknetwork/cli

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:

• Config file exists with 600 permissions
• API key present and format-valid
• DNS + TLS reachability of the base URL
• /api/v1/health reports healthy
• Key accepted by the server
• tork.config.json present in the current directory (warn only)
• Tork SDK installed in the project — passes for tork-governance (local mode) or @torknetwork/sdk (cloud mode) and reports which, with version (warn only)
• 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.