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

Deprecated

As of 0.30.0, agentsview token-use is a deprecated alias for agentsview session usage. Both commands accept the same <session-id> argument. token-use always emits the same JSON shape that session usage --format json emits (now extended with a cost estimate). New scripts should use agentsview session usage.

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

agentsview token-use <session-id>

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. Raw session IDs emitted by the underlying agent are also accepted 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.

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,
  "has_token_data": true,
  "cost_usd": 2.41,
  "has_cost": true,
  "models": ["claude-opus-4-7"],
  "server_running": false
}

See agentsview session usage for the full field reference and exit-code contract.

---

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
--watch	false	Run continuously, pushing on change plus a periodic floor
--debounce	30s	Coalesce window after a change before pushing (--watch only)
--interval	15m	Periodic floor push interval (--watch only)

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 pg service

Install and manage the PostgreSQL auto-push service, which runs agentsview pg push --watch in the background. Supported service managers are launchd on macOS and systemd --user on Linux. See PostgreSQL Sync — agentsview pg service for setup notes.

agentsview pg service install
agentsview pg service status
agentsview pg service logs [-f]
agentsview pg service start
agentsview pg service stop
agentsview pg service uninstall

Command	Description
install	Generate the service unit, enable it, and start it
status	Show the service-manager status plus last successful push
logs -f	Follow pg-watch.log under the AgentsView data directory
start	Start the installed service
stop	Stop the installed service
uninstall	Stop and remove the service unit

---

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
agentsview session search <pattern>      # content search across sessions
agentsview session usage <id>            # token usage and cost estimate

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 secrets

Scan for and list detected secret leaks across sessions, with matches redacted by default. See Secret Scanning for the full detector set, storage shape, and HTTP API.

agentsview secrets scan [flags]   # scan sessions for leaks
agentsview secrets list [flags]   # list stored findings

secrets scan walks the archive, applies the full ruleset (definite + candidate tiers), and writes new findings to the secret_findings table. Pass --backfill to scan only sessions that haven’t yet been scanned at the current ruleset version — the inline scan that runs during sync only stamps definite-tier findings, so --backfill is how you pick up the heuristic candidates without re-scanning the whole archive.

secrets list returns redacted findings by default. Pass --reveal to print the raw values — this only works against a localhost-bound daemon and emits a warning to stderr.

Flag	Used by	Description
--format	both	human or json (inherited from secrets)
--backfill	scan	Scan only sessions not yet scanned at the current ruleset version
--project	both	Limit to a project
--agent	both	Limit to an agent
--date-from	both	Sessions on or after YYYY-MM-DD
--date-to	both	Sessions on or before YYYY-MM-DD
--rule	list	Filter by rule name (e.g. aws-access-key)
--confidence	list	definite, candidate, or all (default definite)
--reveal	list	Show unredacted values (localhost-only)
--limit	list	Max findings (default 50, max 500)
--cursor	list	Pagination cursor from a previous response

---

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
QCLAW_DIR	~/.qclaw/agents	QClaw 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
QWEN_PROJECTS_DIR	~/.qwen/projects	Qwen Code projects directory
WORKBUDDY_PROJECTS_DIR	~/.workbuddy/projects	WorkBuddy projects 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 and ~/.local/share/kiro-cli	Kiro CLI sessions directory (JSONL and SQLite)
KIRO_IDE_DIR	(platform-specific)	Kiro IDE sessions directory
FORGE_DIR	~/.forge	Forge directory (contains .forge.db)
PIEBALD_DIR	~/.local/share/piebald	Piebald directory (contains app.db)
ANTIGRAVITY_DIR	~/.gemini/antigravity	Google Antigravity IDE sessions directory
ANTIGRAVITY_CLI_DIR	~/.gemini/antigravity-cli	Google Antigravity CLI sessions directory
ANTIGRAVITY_KEY		Optional key for decrypting Antigravity CLI .pb transcripts (defaults to summary mode without it)
AGENTSVIEW_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:

AGENTSVIEW_DATA_DIR=/tmp/av-test agentsview serve