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.