CLI Reference

Commands

agentsview / agentsview serve

Start the HTTP server with embedded web UI.

agentsview [flags]
agentsview serve [flags]

Flag	Default	Description
-host	127.0.0.1	Host to bind to
-port	8080	Port to listen on
-browser	false	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                          # defaults
agentsview -port 9090               # custom port
agentsview -browser                 # open browser on startup
agentsview -public-url https://agents.example.com  # remote access

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

Examples:

agentsview sync          # incremental sync and exit
agentsview sync -full    # full resync and exit

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

---

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 v0.1.0 (abc1234) built 2025-01-15

---

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.

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 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 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
AMP_DIR	~/.local/share/amp/threads	Amp threads directory
VSCODE_COPILOT_DIR	(platform-specific)	VS Code Copilot sessions 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_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