CLI Reference

Commands

agentsview serve

Start the HTTP server with embedded web UI.

agentsview serve [flags]

As of 0.23.0, starting the server requires the explicit serve subcommand. Running plain agentsview shows help instead of starting the web UI.

Flag	Default	Description
--host	127.0.0.1	Host to bind to
--port	8080	Port to listen on
--no-browser	false	Don’t open browser on startup
--no-update-check	false	Disable automatic update checks
--public-url		Public URL for hostname or proxy access
--public-origin		Trusted browser origin (repeatable/comma-separated)
--proxy		Managed proxy mode (caddy)
--caddy-bin	caddy	Caddy binary path
--proxy-bind-host	127.0.0.1	Interface for managed proxy
--public-port	8443	External port for managed proxy
--tls-cert		TLS certificate path
--tls-key		TLS key path
--allowed-subnet		Client CIDR allowlist (repeatable/comma-separated)

The server auto-discovers an available port if 8080 is busy. See Remote Access for details on the remote access and proxy flags.

Examples:

agentsview serve                                # defaults
agentsview serve --port 9090                    # custom port
agentsview serve --no-browser                   # disable browser auto-open
agentsview serve --public-url https://agents.example.com

On startup, the server:

1. Loads or creates ~/.agentsview/sessions.db
2. Runs initial sync across all discovered session directories
3. Starts the file watcher (500ms debounce)
4. Starts periodic sync (every 15 minutes)
5. Serves the Svelte SPA and REST API

The server shuts down cleanly on Ctrl+C, flushing the database and stopping file watchers.

---

agentsview sync

Run the sync engine to populate the database, then exit without starting the HTTP server. Useful for scripting, CI, or refreshing data after config changes.

agentsview sync [flags]

Flag	Default	Description
--full	false	Force a full resync regardless of data version
--host		SSH hostname for remote sync
--user		SSH username for remote sync
--port	22	SSH port for remote sync

Examples:

agentsview sync           # incremental sync and exit
agentsview sync --full    # full resync and exit
agentsview sync --host buildbox.local
agentsview sync --host buildbox.local --user wes --port 2222

After syncing, a summary of session and message counts is printed to stdout.

When --host is set, AgentsView performs a remote sync over SSH: it resolves the supported agent session directories on the remote machine, transfers the source session data locally, and indexes it into your local archive.

---

agentsview prune

Delete sessions matching one or more filters. At least one filter is required.

agentsview prune [flags]

Flag	Default	Description
--project		Sessions whose project contains this substring
--max-messages	-1	Sessions with at most N messages
--before		Sessions that ended before this date (YYYY-MM-DD)
--first-message		Sessions whose first message starts with this text
--dry-run	false	Show what would be pruned without deleting
--yes	false	Skip confirmation prompt

Examples:

# Preview what would be deleted
agentsview prune --project "scratch" --dry-run

# Delete short sessions from before 2025
agentsview prune --max-messages 2 --before 2025-01-01

# Delete sessions starting with a specific message
agentsview prune --first-message "test" --yes

# Combine filters (AND logic)
agentsview prune --project "old-project" --max-messages 5 --before 2025-06-01

The prune command displays the number of sessions deleted and disk space reclaimed. Use --dry-run first to verify the filter matches what you expect.

---

agentsview version

Print the version, git commit, and build date.

agentsview version

agentsview 0.23.0 (commit d49f1a9, built 2026-04-19)

---

agentsview usage daily

Report token usage and estimated cost aggregated by local-time day, scoped to the last 30 days by default. See Token Usage & Costs for a full write-up, including benchmarks against ccusage.

agentsview usage daily [flags]

Flag	Default	Description
--json	false	Emit JSON instead of a terminal table
--since	30 days ago	Start date (YYYY-MM-DD), inclusive
--until		End date (YYYY-MM-DD), inclusive
--all	false	Scan all history; overrides the default 30-day window
--agent		Filter by agent name
--breakdown	false	Show indented per-model rows under each day
--offline	false	Skip the LiteLLM pricing fetch; use embedded fallback
--no-sync	false	Skip the on-demand sync pass before querying
--timezone	system	IANA timezone name for date bucketing

Examples:

agentsview usage daily                           # last 30 days
agentsview usage daily --all                     # full history
agentsview usage daily --since 2026-04-01 --breakdown
agentsview usage daily --json --agent claude

---

agentsview usage statusline

Print today’s total estimated cost as a single line, for shell prompts and tmux status lines.

agentsview usage statusline [flags]

Flag	Default	Description
--agent		Filter by agent name
--offline	false	Use embedded fallback pricing only
--no-sync	false	Skip on-demand sync

Example:

$ agentsview usage statusline
$9.61 today

See Token Usage & Costs for integration examples (Starship, tmux).

---

agentsview token-use

Print machine-readable token usage data for a single session.

agentsview token-use <session-id>

Use this command when you want structured token usage output for shell scripts, CI jobs, or other automation. Pass a session ID from the session detail header.

Session ID format depends on the agent. For example, Claude root sessions usually use UUIDs like 550e8400-e29b-41d4-a716-446655440000, Claude subagents use IDs like agent-a86574e, and some other agents use prefixes such as codex:my-session-id.

As of 0.23.0, token-use also accepts raw session IDs emitted by the underlying agent when AgentsView can resolve them back to the canonical stored session.

If the AgentsView server is already running, the command reads the current database state. If no server is running, it performs an on-demand sync for the requested session first, then returns the stored token totals.

The JSON output format is experimental and may change.

Example:

agentsview token-use 550e8400-e29b-41d4-a716-446655440000

{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent": "claude",
  "project": "my-project",
  "total_output_tokens": 15230,
  "peak_context_tokens": 84000,
  "server_running": false
}

total_output_tokens is the session’s total generated output tokens. peak_context_tokens is the highest context-token count seen during that session. server_running indicates whether the command used an already-running AgentsView server rather than falling back to an on-demand session sync.

---

agentsview pg push

Sync sessions from local SQLite to PostgreSQL. See PostgreSQL Sync for full documentation.

agentsview pg push [flags]

Flag	Default	Description
--full	false	Force full local resync and re-push
--projects		Comma-separated projects to push (inclusive)
--exclude-projects		Comma-separated projects to exclude from push
--all-projects	false	Ignore configured project filters for this run

See PostgreSQL Sync — Project Filtering for details on how filtering interacts with the push watermark.

---

agentsview pg status

Show PostgreSQL sync status.

agentsview pg status

---

agentsview pg serve

Start a read-only web UI backed by PostgreSQL. See PostgreSQL Sync for full documentation.

agentsview pg serve [flags]

Accepts the same serve flags (--host, --port, --proxy, etc.) plus PostgreSQL configuration from config.toml.

---

agentsview projects

List all projects in the local database with their session counts.

agentsview projects [flags]

Flag	Default	Description
--json	false	Output as a JSON array

Examples:

agentsview projects         # tabular output
agentsview projects --json   # JSON array

---

agentsview health

Inspect session intelligence in a human-friendly CLI view. See Session Intelligence for the scoring and signal model.

agentsview health [session-id] [flags]

Flag	Default	Description
--json	false	Output JSON instead of terminal text
--limit	20	Number of sessions to list when no session ID is given

Examples:

agentsview health
agentsview health --limit 50
agentsview health 550e8400-e29b-41d4-a716-446655440000
agentsview health agent-a86574e --json

Without a session ID, the command lists recent sessions with grade and outcome columns. With a session ID, it prints the detailed signal counts for that session.

---

agentsview stats

Experimental window-scoped workspace analytics across sessions and git activity. See Stats for the full write-up.

agentsview stats [flags]

Flag	Default	Description
--format	human	Output format: human or json
--since	28d	Start of window, either YYYY-MM-DD or a compact duration like 28d
--until		End of window as YYYY-MM-DD
--agent	all	Restrict to one agent or use all
--include-project		Repeatable project allowlist
--exclude-project		Repeatable project blocklist
--timezone	local	Timezone used for temporal reporting

Examples:

agentsview stats
agentsview stats --format json --since 2026-04-01 --until 2026-04-15
agentsview stats --agent claude --include-project agentsview

The command is experimental. The exact human output may change, and the JSON output should be treated as a moving surface even though it currently carries schema_version: 1.

---

agentsview import

Import Claude.ai or ChatGPT conversations into the local database. See Chat Import for full documentation.

agentsview import --type <type> <path>

Flag	Default	Description
--type		Import type: claude-ai or chatgpt (required)

The path can be a .zip file, a conversations.json file (Claude.ai only), or a directory containing the extracted export.

Examples:

agentsview import --type claude-ai ~/Downloads/claude.zip
agentsview import --type chatgpt ~/Downloads/chatgpt.zip
agentsview import --type claude-ai ./conversations.json

---

agentsview session

Programmatic access to session data for scripts, automation agents, and CI jobs. See Session API for full documentation, including stability guarantees, transport auto-detection, and every subcommand.

agentsview session get <id>              # metadata + signals
agentsview session list [flags]          # filtered list
agentsview session messages <id>         # paginated messages
agentsview session tool-calls <id>       # flat tool-call list
agentsview session export <id>           # stream raw source file
agentsview session sync <path-or-id>     # parse + insert
agentsview session watch <id>            # NDJSON event stream

Use agentsview health for a human-first signal view and Session API for the full programmatic contract, including transport behavior and markdown export details.

---

agentsview help

Print usage information.

agentsview help

Environment Variables

Variable	Default	Description
CLAUDE_PROJECTS_DIR	~/.claude/projects	Claude Code projects directory
CODEX_SESSIONS_DIR	~/.codex/sessions	Codex sessions directory
COPILOT_DIR	~/.copilot	Copilot CLI sessions directory
CURSOR_PROJECTS_DIR	~/.cursor/projects	Cursor transcripts directory
GEMINI_DIR	~/.gemini	Gemini CLI directory
OPENCODE_DIR	~/.local/share/opencode	OpenCode data directory
OPENHANDS_CONVERSATIONS_DIR	~/.openhands/conversations	OpenHands CLI conversations directory
AMP_DIR	~/.local/share/amp/threads	Amp threads directory
VSCODE_COPILOT_DIR	(platform-specific)	VS Code Copilot sessions directory
POSITRON_DIR	(platform-specific)	Positron Assistant user directory
OPENCLAW_DIR	~/.openclaw/agents	OpenClaw agents directory
PI_DIR	~/.pi/agent/sessions	Pi sessions directory
IFLOW_DIR	~/.iflow/projects	iFlow projects directory
ZENCODER_DIR	~/.zencoder/sessions	Zencoder sessions directory
KIMI_DIR	~/.kimi/sessions	Kimi sessions directory
WARP_DIR	(platform-specific)	Warp database directory
HERMES_SESSIONS_DIR	~/.hermes/sessions	Hermes Agent sessions directory
CORTEX_DIR	~/.snowflake/cortex/conversations	Cortex Code conversations directory
KIRO_SESSIONS_DIR	~/.kiro/sessions/cli	Kiro CLI sessions directory
KIRO_IDE_DIR	(platform-specific)	Kiro IDE sessions directory
AGENT_VIEWER_DATA_DIR	~/.agentsview	Data directory (database, config)
AGENTSVIEW_PG_URL		PostgreSQL connection URL
AGENTSVIEW_PG_MACHINE		Machine name for PG push sync
AGENTSVIEW_PG_SCHEMA	agentsview	PostgreSQL schema name
AGENTSVIEW_GITHUB_TOKEN		GitHub token used by agentsview stats for PR aggregation
AGENTSVIEW_DISABLE_UPDATE_CHECK		Set to 1 to disable the update check

Environment variables override the built-in defaults. Set them in your shell profile or pass them inline:

AGENT_VIEWER_DATA_DIR=/tmp/av-test agentsview serve