@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 @tork/cli --help

# Homebrew
brew install torkjacobs/tap/tork

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)
--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/*), installs the tork-governance SDK with the matching package manager, and writes tork.config.json:

{
  "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
--yes, -y	Skip prompts (defaults to Node when both stacks are present)
--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 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-governance SDK installed in the project, 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 (fetched live when possible), base URL, and config path.

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 @tork/cli doctor --json
      - run: npx @tork/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 tork-governance / pip install tork-governance
Colored output breaks log parsing	ANSI codes in CI logs	Set NO_COLOR=1 or use --json

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.