CLI Reference

Complete command-line interface reference for Perspt.

Global Options

perspt [OPTIONS] <COMMAND>

Option

Description

-v, --verbose

Enable verbose logging

-c, --config <FILE>

Configuration file path

-h, --help

Print help information

-V, --version

Print version

Commands Overview

Command

Description

chat

Start interactive TUI chat session

agent

Run SRBN agent for autonomous coding

init

Initialize project configuration

config

Manage configuration settings

ledger

Query and manage Merkle ledger

status

Show current agent status

abort

Abort current agent session

resume

Resume paused or crashed session

logs

View LLM request/response logs

simple-chat

Simple CLI chat mode (no TUI)

perspt chat

Usage: perspt chat [OPTIONS]

Start an interactive TUI chat session.

-m, --model <MODEL>

Model to use (e.g., gpt-5.2)

Example:

perspt chat
perspt chat --model claude-opus-4.5

perspt agent

Usage: perspt agent [OPTIONS] <TASK>

Run the SRBN agent for autonomous coding.

Arguments:

<TASK>

Task description or path to task file

Model Options:

--model <MODEL>

Override all model tiers

--architect-model <M>

Model for planning (deep reasoning)

--actuator-model <M>

Model for code generation

--verifier-model <M>

Model for stability checking

--speculator-model <M>

Model for fast lookahead

Execution Options:

-w, --workdir <DIR>

Working directory (default: current)

-y, --yes

Auto-approve all actions

--auto-approve-safe

Auto-approve read-only operations

-k, --complexity <K>

Max complexity before approval (default: 5)

--mode <MODE>

cautious, balanced, or yolo

SRBN Options:

--energy-weights <α,β,γ>

Lyapunov weights (default: 1.0,0.5,2.0)

--stability-threshold <ε>

Convergence threshold (default: 0.1)

Limit Options:

--max-cost <USD>

Maximum cost in dollars (0 = unlimited)

--max-steps <N>

Maximum iterations (0 = unlimited)

Execution Options:

--defer-tests

Defer tests until sheaf validation (faster iteration)

--log-llm

Log all LLM requests/responses to database

Examples:

perspt agent "Create a calculator"
perspt agent -y -w ./project "Add tests"
perspt agent --architect-model gpt-5.2 --actuator-model claude-opus-4.5 "Build API"

perspt init

Usage: perspt init [OPTIONS]

Initialize project configuration.

--memory

Create PERSPT.md project memory file

--rules

Create .perspt/rules.star policy file

Example:

perspt init --memory --rules

perspt config

Usage: perspt config [OPTIONS]

Manage configuration settings.

--show

Display current configuration

--set <KEY=VALUE>

Set a configuration value

--edit

Open in $EDITOR

Examples:

perspt config --show
perspt config --set default.model=gpt-5.2
perspt config --edit

perspt ledger

Usage: perspt ledger [OPTIONS]

Query and manage the Merkle change ledger.

--recent

Show recent commits

--rollback <HASH>

Rollback to specific commit

--stats

Show ledger statistics

Examples:

perspt ledger --recent
perspt ledger --rollback abc123
perspt ledger --stats

perspt status

Usage: perspt status

Show current agent session status. Displays:

  • Session ID

  • Current task

  • Energy levels (V_syn, V_str, V_log)

  • Token usage

perspt abort

Usage: perspt abort [OPTIONS]

Abort the current agent session.

-f, --force

Force abort without confirmation

perspt resume

Usage: perspt resume [SESSION_ID]

Resume a paused or crashed session.

[SESSION_ID]

Session ID to resume (optional, uses latest if omitted)

perspt simple-chat

Usage: perspt simple-chat [OPTIONS]

Simple command-line chat mode for scripting and automation. No TUI - just a prompt with streaming responses.

-m, --model <MODEL>

Model to use for chat

--log-file <FILE>

Log session to file

Examples:

perspt simple-chat
perspt simple-chat --log-file session.txt
echo "Explain Rust" | perspt simple-chat

perspt logs

Usage: perspt logs [OPTIONS] [SESSION_ID]

View and analyze LLM request/response logs from agent sessions.

Arguments:

[SESSION_ID]

Session ID to view (optional)

Options:

--last

Show logs from most recent session

--stats

Show usage statistics instead of individual requests

--tui

Launch interactive TUI logs viewer

Examples:

# View most recent session logs
perspt logs --last

# Interactive TUI viewer
perspt logs --tui

# Usage statistics
perspt logs --stats

# Specific session
perspt logs abc123-session-id

Exit Codes

Code

Meaning

0

Success

1

General error

2

Configuration error

3

Provider/API error

4

Agent aborted by user

See Also