CLI Commands

The tervos CLI is the primary interface for managing organizations, running agents, and inspecting state.

Install globally or use via npx:

npm install -g tervos
# or
npx tervos <command>

`tervos init`

Initialize a new Tervos organization in the current directory.

tervos init [--template <name>]

Flags

Flag	Description	Default
`--template <name>`	Starter template to use	`minimal`

Templates

Name	Description
`minimal`	Single supervised agent, no projects
`demo`	Three agents (CEO, Analyst, Writer) with a demo research project

Example

$ tervos init --template demo

✓ Created TERVOS.yaml
✓ Created .tervos/ directory

Organization: Demo AI Corp
Agents: ceo, analyst, writer
Projects: demo-research (2 tasks)

Run `tervos start --dev` to begin.

`tervos start`

Bootstrap and start the organization.

tervos start [--dev] [--auto-approve]

Flags

Flag	Description
`--dev`	Development mode: activates all agents automatically, auto-approves all actions
`--auto-approve`	Auto-approve all pending actions (without full dev mode)

Example

$ tervos start --dev

✓ Manifest validated
✓ Organization DID created: did:key:z6Mk...
✓ Event store initialized
✓ Policy engine loaded (7 default policies)
✓ 3 agents registered and activated
✓ Organization bootstrapped

[dev mode] Auto-approve enabled. All actions will proceed without human review.

Listening for commands...

`tervos status`

Display current organization state: agents, tasks, and budget.

tervos status

Example output

Organization: Demo AI Corp
Status: ACTIVE
Agents: 3 active, 0 suspended

AGENT        ROLE              STATE   AUTONOMY        BUDGET USED
ceo          CEO               ACTIVE  semi-autonomous $12.40 / $30.00
analyst      Research Analyst  ACTIVE  semi-autonomous $8.20 / $40.00
writer       Content Writer    ACTIVE  semi-autonomous $4.10 / $30.00

Tasks: 1 active, 1 completed, 0 blocked
Events: 47 total

`tervos audit`

Query the organization’s event log.

tervos audit [--agent <id>] [--type <type>] [--since <datetime>]

Flags

Flag	Description	Example
`--agent <id>`	Filter to events involving a specific agent	`--agent ceo`
`--type <type>`	Filter by event type (supports wildcards)	`--type org.task.*`
`--since <datetime>`	Show events after this timestamp	`--since 2026-03-01T00:00:00Z`

Example

$ tervos audit --type org.task.*

SEQ  TIMESTAMP              TYPE                    AGENT     SUMMARY
42   2026-03-19T10:00:00Z   org.task.created        ceo       Created: Research competitor landscape
43   2026-03-19T10:00:01Z   org.task.assigned       ceo       Assigned to: analyst
44   2026-03-19T10:00:02Z   org.task.started        analyst   Task started
...

`tervos approve`

Approve a pending action.

tervos approve <id> [--comment <text>]

Arguments

Argument	Description
`<id>`	The pending action ID (from `tervos status` or audit log)

Flags

Flag	Description
`--comment <text>`	Optional approval comment, recorded in the event log

Example

$ tervos approve act_01234 --comment "Reviewed and approved for production"

✓ Action act_01234 approved
  Comment: "Reviewed and approved for production"
  Recorded as: policy.approval.granted (seq 58)

`tervos deny`

Deny a pending action.

tervos deny <id> --reason <text>

Arguments

Argument	Description
`<id>`	The pending action ID

Flags

Flag	Required	Description
`--reason <text>`	Yes	Reason for denial (required, recorded in audit log)

Example

$ tervos deny act_01235 --reason "Budget limit reached for this period"

✓ Action act_01235 denied
  Reason: "Budget limit reached for this period"
  Recorded as: policy.approval.denied (seq 59)

`tervos validate`

Validate a TERVOS.yaml manifest without bootstrapping.

tervos validate [path]

Arguments

Argument	Description	Default
`path`	Path to the manifest file	`./TERVOS.yaml`

Example

$ tervos validate

✓ Schema version: tervos/v1
✓ 3 agents defined
✓ Reporting hierarchy: valid DAG
✓ Budget allocations: $100 / $100 limit
✓ 2 tasks, all assignees valid
✓ Manifest is valid.

If there are errors:

$ tervos validate ./bad-manifest.yaml

✗ Validation failed (2 errors):

  1. agents.writer.reports_to: references undefined agent "cto"
     Fix: define a "cto" agent or change reports_to to an existing agent ID

  2. governance.budget.monthly_limit_usd: sum of agent budgets ($120) exceeds org limit ($100)
     Fix: reduce agent budgets or increase the org monthly_limit_usd

`tervos import`

Import an organization definition from another format.

tervos import --from <format> <path>

Flags

Flag	Required	Description
`--from <format>`	Yes	Source format

Supported formats

Format	Description
`paperclip`	Import from a Paperclip COMPANY.md definition

Example

$ tervos import --from paperclip ./COMPANY.md

✓ Parsed 5 agents from COMPANY.md
✓ Mapped to TERVOS.yaml format
  - All agents set to autonomy_level: supervised (default for imports)
  - Generated did:key identities for all agents
  - Applied default policies

✓ Written to: TERVOS.yaml

`tervos stop`

Suspend the organization and shut down the runtime.

tervos stop

Example

$ tervos stop

Suspending organization...
✓ 3 agents suspended
✓ In-flight tasks checkpointed (2 tasks saved)
✓ Event store flushed
✓ Organization suspended. Run `tervos start` to resume.

`tervos audit --verify`

Verify the integrity of the event hash chain. Every event appended since v0.2.0 is hash-chained; any mutation, deletion, or reordering of stored events breaks the chain.

tervos audit --verify

Example

$ tervos audit --verify

✓ did:key:z6Mk…: chain intact — 23 events verified

# After someone edits events.db directly:
$ tervos audit --verify

✗ did:key:z6Mk…: TAMPER DETECTED at sequence 7 — hash mismatch: event content does not match its recorded hash

Exits 1 if any organization’s chain fails verification. Events written before v0.2.0 have no hash fields and are skipped as a legacy prefix.

`tervos export-evidence`

Export a portable, offline-verifiable evidence bundle (tervos-evidence/v1) of the audit chain — for auditors, compliance reviews, or long-term retention.

tervos export-evidence [--org <did>] [--from <seq>] [--to <seq>] [--sign-as <agentId>] -o <file>

Flag	Description
`--org <did>`	Organization to export (required if the store has several)
`--from / --to <seq>`	Sequence range to include (defaults to everything)
`--sign-as <agentId>`	Sign the bundle with this agent’s Ed25519 key
`--allow-invalid`	Export even if the chain fails verification (the bundle records `chainValid: false`)
`-o, --output <file>`	Output path (required)

Example

$ tervos export-evidence --sign-as ceo -o evidence.json

✓ Evidence bundle written to evidence.json
  org:        did:key:z6Mk…
  events:     23 (seq 1–23)
  chain:      intact (head 4f1c22938…)
  signature:  signed by did:key:z6Mk…

By default the command refuses to export a log that fails chain verification.

`tervos attest`

Emit a signed chain-head receipt (tervos-attestation/v1) — a compact, timestamped statement of “this org’s log had N events with this chain head at this moment”, signed with an agent key. Periodically published receipts make later truncation of the log detectable.

tervos attest [--org <did>] [--sign-as <agentId>] [-o <file>]

Example

$ tervos attest --sign-as ceo
{
  "format": "tervos-attestation/v1",
  "orgDid": "did:key:z6Mk…",
  "sequenceNumber": 23,
  "chainHead": "4f1c22938…",
  "eventsVerified": 23,
  "attestedAt": "2026-06-12T23:53:04.733Z",
  "signerDid": "did:key:z6Mk…",
  "signature": "467434d2…"
}

Refuses to attest if the chain fails verification.

`tervos-verify` (from `@tervos/verify`)

Verify an evidence bundle offline — on any machine, with no Tervos installation, no network access, and no trust in the machine that produced the bundle beyond its signing key.

npx @tervos/verify evidence.json
# or, if installed: tervos-verify evidence.json

Example

$ npx @tervos/verify evidence.json

Bundle:    evidence.json
Org:       did:key:z6Mk…
Events:    23 (23 chained, 0 legacy)
Chain:     ✓ valid
Signature: ✓ valid — signed by did:key:z6Mk…

✓ evidence verified

Exits 0 when the chain is intact and the signature (if present) verifies; 1 otherwise.

`tervos hook`

Record an external runtime action from stdin into the evidence chain. Built for Claude Code hooks — see the Attach Tervos to Claude Code guide.

echo '<hook-json>' | tervos hook [--source claude-code] [--org <id>]

Silent on success (hook-safe); exits 2 with a one-line stderr message on failure. Events land in the external:<source> chain as external.action.recorded.

`tervos tap`

Poll an external runtime’s activity stream and counter-sign each record into the evidence chain.

tervos tap --from paperclip --url http://localhost:3000 [--watch 30]

Flag	Description
`--from <runtime>`	Source runtime (supported: `paperclip`)
`--url <baseUrl>`	Base URL of the running instance
`--activity-path <path>`	Activity endpoint (default `/api/activities`; Paperclip publishes no API docs — adjust to your instance)
`--watch <seconds>`	Keep polling at this interval

Example

$ tervos tap --from paperclip --url http://localhost:3000 --watch 30

✓ counter-signed 17 paperclip activities (chain head 8c41f0a2…)
watching every 30s — ctrl-c to stop

Paperclip’s own audit log is platform-trust — a database it promises not to edit. The tap gives every activity row an independent, cryptographically chained copy that Paperclip cannot rewrite.

`tervos passport`

Emit a Cubitrek-spec Agent Passport (v0.1.0) for an agent, signed with its existing Ed25519 key.

tervos passport <agentId> --domain <domain> [--purpose <text>] [-o file]

Example

$ tervos passport ceo --domain example.com -o agent-passport.json

✓ Agent Passport written to agent-passport.json

To anchor this passport:
  1. Host the file at https://example.com/.well-known/agent-passport.json
  2. Add a DNS TXT record at _agent-passport.example.com:
     v=ap1; kid=key-1; alg=ed25519; pk=TIHbPDCy…

Defaults for purpose, display name, and model come from the agent’s entry in TERVOS.yaml. The emitted document verifies with the reference @cubitrek/agent-passport-verifier.

CLI Commands

tervos init

Flags

Templates

Example

tervos start

Flags

Example

tervos status

Example output

tervos audit

Flags

Example

tervos approve

Arguments

Flags

Example

tervos deny

Arguments

Flags

Example

tervos validate

Arguments

Example

tervos import

Flags

Supported formats

Example

tervos stop

Example

tervos audit --verify

Example

tervos export-evidence

Example

tervos attest

Example

tervos-verify (from @tervos/verify)

Example

tervos hook

tervos tap

Example

tervos passport

Example

`tervos init`

`tervos start`

`tervos status`

`tervos audit`

`tervos approve`

`tervos deny`

`tervos validate`

`tervos import`

`tervos stop`

`tervos audit --verify`

`tervos export-evidence`

`tervos attest`

`tervos-verify` (from `@tervos/verify`)

`tervos hook`

`tervos tap`

`tervos passport`