CLI Reference

Start from help¶

agentsview --help includes a numbered workflow for syncing sources, finding sessions, reading transcripts, and checking usage. It explains session IDs, backend selection, output streams, exit codes, and environment variables. Run agentsview source list --json for the provider catalog, built-in source locations, and environment override names. It does not resolve configured directory arrays. Run agentsview openapi for the API schema.

Use agentsview session --help for common backend and output flags. Core commands include examples and describe their limits.

Recover from CLI errors¶

Failed commands print fatal: <message> followed by hint: <next step> on stderr. The hint names CLI commands, flags, or settings. Unknown commands and flags point to the relevant command's --help.

Commands that accept --json or --format json write one JSON diagnostic line to stderr instead:

{"error":"usage","message":"unknown flag: --bogus","hint":"run `agentsview session list --help` for flags and examples"}

The error value identifies the category: usage, validation, unavailable, authentication, forbidden, conflict, not_found, or the general error. A true --json takes precedence over --format; repeated flags use their final valid values. Rejections on fixed-stream commands also honor the requested JSON error format. Existing warnings can precede the diagnostic on stderr. Success reports, transcript streams, and API response formats keep their existing formats on stdout.

If a session is missing, copy a canonical ID from agentsview session list --json. For a new session, run agentsview source sync on the archive host. If autostart is disabled with AGENTSVIEW_NO_DAEMON=1, run agentsview daemon start before retrying a daemon read. An explicit remote --server needs that host's URL and token, supplied through --server-token-file or AGENTSVIEW_SERVER_TOKEN.

Exit codes¶

Existing command-specific outcomes take precedence over the general error classes. Read the process status separately from stdout: a usage report can be present with exit 3.

capture run preserves the captured command's exit status. session usage keeps exit 3 silent after writing its normal report. session usage-batch keeps per-session exit codes in its result document and succeeds when the batch itself completes. Export cursor/revision errors retain their existing flat JSON documents on stderr. Hidden worker and browser-host protocols keep their existing diagnostics. parse-diff --fail-on-change retains its normal report and exit 1 when changes or parse failures are found. Remote sync failures keep their per-host summary and add recovery advice.

Commands¶

Find a command by task¶

Describe a task to get up to five matching commands:

agentsview cli search "show token cost for a conversation"
agentsview cli search list supported providers --limit 3 --json

Search reads the command tree locally. It needs no configuration, database, daemon, network connection, or credentials. Results use current command paths; hidden legacy commands, help-only groups, browser setup, and interactive service installation are omitted. Eligible actions inside groups remain searchable.

--limit accepts 1–20 (default 5). --json and --format json return {"query":"...","results":[{"command":"...","summary":"...","usage":"..."}]}. An unmatched task succeeds with an empty results array. Text output includes a command help hint for flags and examples. Run agentsview cli for help.

Root help lists command domains. Run agentsview source --help, for example, to find the actions in that domain, then agentsview source sync --help for flags. These command paths follow main; older releases use the legacy names below.

Command migration¶

Related actions now share a noun. Existing command names continue to work for at least one release. They are hidden from root help and completion, and an invoked legacy action prints its replacement on stderr. Flags, arguments, stdout documents, exit codes, HTTP routes, and MCP tools keep their behavior. Daemon, SSH sync, browser host, and parser child protocols keep their existing launch paths.

Keep using agentsview usage grok <csv> to import xAI billing files. Its deprecation notice names report usage grok, which does not exist in 0.47.0.

session prune operates on the local archive. It rejects the session group's inherited --server, --server-token-file, --pg, --json, and --format flags before accessing storage. Use --dry-run to inspect the selection.

agentsview git-hook¶

Add the current agent session to commits in a repository:

agentsview git-hook install

The prepare-commit-msg and commit-msg hooks work together. The first records the message Git prepared; the second adds Agent-Session: <agent>:<session-id> to commits made without an editor, including -m, -F, -C, --amend --no-edit, and merge --no-edit. An unchanged commit template stays untouched so Git can reject it. A conflicted cherry-pick finished with --no-edit or --continue also carries the current session. Editor commits keep their original messages. Git doesn't run commit-msg for git revert --no-edit or rebase picks, so they get no new trailer. Rebase picks keep their existing trailers. Amending from a different session adds a second Agent-Session line.

The hook skips messages containing only blank lines, Git comments, or signoffs. Git still rejects empty messages. A comment-only message such as -m '#123 fix' can still commit when Git retains comments, but gets no trailer. Git doesn't tell hooks whether -s added a signoff, so when a commit template already ends with your own signoff and another hook changes that line, the commit gets no trailer. With core.commentChar=auto, Git picks its comment character per commit and doesn't tell hooks which. The hook then treats lines starting with any of #;@!$%^&|: as possible comments, so a message made only of such lines gets no trailer, and commits that start from a commit template get none either.

AgentsView must be on PATH. A missing or failing binary, or a missing, invalid, or ambiguous session, leaves the commit message unchanged.

Discovery reads the session variable each supported harness sets for the commands its agent runs:

Claude and Codex IDs must be UUIDs. Commits from unlisted harnesses get no trailer unless you set the override pair. When an agent runs inside another agent's shell, such as Pi started from Claude Code, both variables are set. The hook then leaves the message unchanged and prints a warning. Set both AGENTSVIEW_SESSION_AGENT and AGENTSVIEW_SESSION_ID to resolve this ambiguity or override discovery. Override agent names accept lowercase letters, digits, and hyphens, up to 32 characters, starting with a letter or digit. IDs for agents other than Claude and Codex accept letters, digits, dots, underscores, and hyphens, up to 128 characters, starting with a letter or digit.

Installation writes both hooks into the directory Git uses. Rerunning it succeeds without changing byte-identical hooks. A core.hooksPath setting, including a global one, makes installation apply to every repository sharing that path. The two hooks only work as a pair. When either one already exists with other content, installation writes nothing and prints the steps for both: the line to add to each existing hook, and the file to create for a missing one. Put the prepare-commit-msg line right after the hook's first line, so it saves the template before your hook edits it:

if command -v agentsview >/dev/null 2>&1; then agentsview git-trailer-prepare "$@" || :; fi

Put the commit-msg line last, before any final exit, so it stamps after your hook's edits. It keeps the status of your hook's last command and doesn't exit, so a failing check still rejects the commit and a final exit still decides:

agentsview_status=$?; if command -v agentsview >/dev/null 2>&1; then agentsview git-trailer "$1" || :; fi; (exit "$agentsview_status") && :

To remove the hooks, delete the installed prepare-commit-msg and commit-msg files. For shared hooks, remove the added lines.

agentsview archive¶

Available in 0.46.0 and later, these commands retain captures from several machines, recover their original files, and reparse Claude and Codex sessions after the original directories are gone. capture can snapshot live SQLite databases. Regular files must stay unchanged while copied; a changing transcript aborts the capture. Stop source writers for the final retirement capture. Stop the destination daemon before import, reparse, backup or extraction. Those archive writes refuse to run while another process owns the database.

Use an isolated data directory for the receiving archive. Seed it from the capture of the installation being retired, as shown below. Older or alternate databases remain supplemental files; these commands do not merge databases. After a rehearsal, assemble the final archive in a new directory from final captures. Later imports retain changed versions for recovery, but do not update already accepted browsable sessions or deletion policy. Ongoing collection and source advancement are outside this workflow.

Create a capture on the source machine. Select roots explicitly; files retains supplemental trees without parsing them:

agentsview archive capture /media/backup/source-capture \
  --root claude="$HOME/.claude/projects" \
  --root codex="$HOME/.codex/sessions" \
  --root files=/path/to/supplemental-history

The standard Claude projects and Codex sessions/archived_sessions roots include their parent directory to retain companion files. Only the selected session directory is parsed. Selecting a provider home includes its existing conventional session directories. No other home-directory scanning occurs. Capture also records other spellings of each root that the captured database uses, such as a path through a symlink, after checking that they resolve to the same directory. Reparse then recognizes those seeded sessions after the originals are gone.

Capture reads the installation ID without creating one in the source. It reuses known raw-sync root IDs. When it generates identities, the JSON report lists them under new_identities; pass --identity-from PREVIOUS/capture.json on subsequent captures to reuse them. A previous descriptor from another installation, or conflicting checkpoint identities, causes an error. The descriptor alone is sufficient for identity reuse; the older captured files are not read. If the source AgentsView data directory moved, identity reuse preserves its original application-root binding and records its current location separately. Import still requires the complete capture directory.

Regular files are streamed and checked. SQLite databases use online backups, including committed WAL contents. Symlinks, special files and recognized credential/settings files are omitted and listed. Original application config is replaced by allowlisted recovery settings. This does not redact transcripts or database content. Exclusions include .git-credentials and Claude's ide/ runtime metadata. An ordinary artifact vault currently prevents capture; its stopped-owner copying support is still required. If the source already contains a raw archive, use archive backup to preserve its vault as well as its database; capture refuses that input.

--writers-stopped records your attestation that source writers were stopped; it does not stop them. A rolling capture is not a final retirement cutoff. The destination must be new and outside the selected inputs. Failed captures are not published. The completed directory contains capture.json, a hashed inventory and root-relative files; move the directory as a whole. Import rejects any file the inventory does not list. On macOS, copy with rsync -a or COPYFILE_DISABLE=1 tar, because plain tar adds ._* metadata files.

Import verifies the generated descriptor and every file before accepting sources. Handwritten import specifications are no longer accepted. The capture and import reports include counts from the captured database. Missing or unsupported preflight data, artifact origins/imports or qualified session IDs block assembly pending identity integration.

To preserve existing history and curation, create the archive with --seed:

AGENTSVIEW_DATA_DIR=/new/archive agentsview archive import --seed \
  --spec /media/backup/source-capture/capture.json

The target must not exist and must be outside the capture. Seed import preserves the captured database, installation identity and assets, including session and message IDs, stars, pins, names, trash and permanent exclusions. It also retains the raw files. It checks the assembled archive before publishing the directory; a failed assembly leaves no partial destination. Allow space for the database, retained raw files and a temporary database copy if a rebuild is needed.

Seed import enables archive-only mode before any rebuild or startup. It does not reparse sources or adopt historical machine names. The report's unowned_machines lists unresolved machine keys with session and worktree-rule counts; use db adopt-machine only for keys you explicitly own. An existing raw archive in the seed is refused; use its archive backup recovery point instead. Empty and local machine labels already denote the seed's own installation and are recognized during reparse. Other named machines still require proven ownership.

Add another machine's capture with archive import --spec OTHER/capture.json, then explicitly reparse its accepted sources. A hard import failure can leave retained raw objects and already accepted sources in the target. Retrying the same capture is safe and reuses that evidence. Sessions remain attributed to the source installation even if the archive moves or a display label changes. These commands require an archive-only destination created by seed import or restore. They refuse an everyday database instead of converting it. Foreign session IDs include that installation ID; equal native IDs or paths on different machines remain separate observations. The seed keeps its existing session IDs. Unrelated identity collisions stop the reparse without publishing its scratch database.

Foreign stars, pins, names and project rules are retained in the captured database but are not merged. Source trash and permanent deletions suppress publication of those sessions; their original files remain recoverable. Reparse reports the intentional skips as suppressed. Deletion evidence with unresolved machine ownership blocks regular import; adopt only proven ownership on the source and recapture. The first import freezes its deletion policy. A later capture with changed deletion state retains the new files as evidence and reports a conflict; it does not change the accepted projection.

export AGENTSVIEW_DATA_DIR=/new/archive
agentsview archive sources
agentsview archive verify
agentsview archive backup /media/backup/repository
# Use snapshot_id from the backup report for both commands:
agentsview archive verify --repository /media/backup/repository --snapshot SNAPSHOT_ID
agentsview archive restore /media/backup/repository /restored/archive --snapshot SNAPSHOT_ID
AGENTSVIEW_DATA_DIR=/restored/archive agentsview archive verify
AGENTSVIEW_DATA_DIR=/restored/archive agentsview archive reparse --all
# Use capture_id from the capture or import report to recover one version:
AGENTSVIEW_DATA_DIR=/restored/archive agentsview archive extract /new/capture --capture CAPTURE_ID

Restore and extract require new destinations. Backup creates a repository or adds a snapshot to an existing one. Backup and restore reject overlapping source and destination directories. extract --capture ID recovers that capture's exact files, including supplemental files and versions that conflicted on import. It recreates capture.json, inventory.json and roots/ under the original configured root IDs. The result passes the same complete-file verification as the original capture and can be imported using --spec /new/capture/capture.json. Extraction does not change accepted sources or browsable history.

Without --capture, extraction writes all retained native files under their archive root IDs. These IDs distinguish installations and providers. If any path has different retained versions, this mode fails before creating output or reading content. Repeated captures normally have different database and report files, so use --capture to choose a complete version. Failed extraction removes its partial output.

Import reports retained files and bytes separately from accepted provider sources. Files outside Claude and Codex capture plans remain supplemental. A conflicting source is retained as evidence and reported as a coverage gap; it never replaces the accepted source automatically. An import with gaps exits unsuccessfully after printing its report. No files are pruned automatically.

reparse --manifest ID selects specific accepted sources; repeat the flag or supply comma-separated IDs. --all must be explicit. Reparse applies the receiving archive's result_content_blocked_categories. Reparsing clones SQLite once for the batch and uses the normal sync engine, including its large-Codex streaming path. It installs the replacement only after all selected sources succeed. Failed work leaves the previous browsable archive in place and records an error. Session ownership conflicts are reported without merging identities. Allow scratch space for the full database, its WAL, and materialized source files. --scratch-bytes limits each materialized source to 16 GiB by default; it does not cap total scratch usage.

verify reads every retained object and accepted manifest. Backup verifies that closure, holds the writer and raw-vault locks, and creates a consistent SQLite snapshot through Docbank's portable backup API. It retains assets, installation identity, content/image retention policy and the original machine label. An existing ordinary artifact vault is currently rejected because its stopped-owner capture is not implemented; it is never silently omitted.

Keep the backup report's repository ID, snapshot ID, application build and minimum reader version. Restore and repository verification require --snapshot ID even when the repository contains only one snapshot. Application extras over 64 MiB require Kit reader version 6; older binaries cannot use any part of that repository after it contains such a snapshot.

Restore stages the selected snapshot and checks SQLite integrity, every accepted source object, and referenced message/tool images before publishing a new directory. Missing or corrupt referenced images also prevent backup. An older database is rebuilt from its stored sessions with all live providers disabled. Allow space for the restored data and temporary complete copies of large extras.

Original runtime configuration and connection credentials are not copied from configuration. Seed import and restore generate fresh local authentication and loopback settings. Previously retained raw files are preserved without redaction and may contain credentials. Seeded and restored databases are permanently archive-only: foreground starts, background starts and restarts do not scan the receiving machine. Ordinary sync, source transfers over HTTP or SSH, ChatGPT, Claude.ai and Gemini Apps imports, artifact exchange, mirror publication and raw-sync watch are refused. Browsing, curation, archive import, verification, extraction, backup and explicit reparse remain available. Use a separate data directory to collect new local sessions; no runtime flag or config setting disables archive-only mode.

Startup resync keeps archive-only sessions and their acceptance records without opening the raw vault. Reparsing them always requires an explicit command. Continuous capture, cross-device merging, team permissions, cloud storage, and online backup are outside this first implementation.

agentsview capture¶

Capture and export the usage of one exact non-interactive automation run without starting the daemon, server, web interface, or watchers:

agentsview capture run \
  --provider claude \
  --occurrence build-42 \
  --capture-dir ./capture-build-42 \
  --result ./usage-build-42.json \
  -- claude -p "Diagnose the build failure."

agentsview capture report \
  --capture-dir ./capture-build-42 \
  --result ./usage-build-42.json

capture run supports direct claude -p and codex exec --json producer adapters. It leaves child standard input, output, error, and exit outcome intact. The result always uses a separate file; recovery-only capture report may use --result - for standard output. See One-shot CI capture for the result contract, retry behavior, failure codes, and a complete GitHub Actions job.

agentsview source raw¶

Capture supported local provider sources and upload their raw generations to hosted custody:

export AGENTSVIEW_RAW_SYNC_URL=https://agents.example.com
export AGENTSVIEW_RAW_SYNC_DEVICE_ID=device-id
export AGENTSVIEW_RAW_SYNC_CREDENTIAL=device-credential
agentsview source raw watch
agentsview source raw status
agentsview source raw server-status

raw-sync watch runs an initial bounded audit, watches for filesystem changes, and retries interrupted uploads from its durable local checkpoint. The device credential is accepted only through AGENTSVIEW_RAW_SYNC_CREDENTIAL, never as a command-line flag. --server and --device-id override their corresponding environment variables.

raw-sync status reads the checkpoint without creating one and prints path-free JSON containing capture, queue, retry, failure, and coverage state. S3 roots are not captured. raw-sync server-status reads hosted status with the status token scope and prints the server fields plus pipeline_depth and last_parse_latency_seconds. The latency describes the most recently completed current head, not the age of pending work. Its credential is read only from AGENTSVIEW_RAW_SYNC_CREDENTIAL. A server HTTP 404 is an error; use raw-sync status to read local state. A deployment operator must provision the device ID and credential; there is no public enrollment command yet. See Hosted Raw Sync for the current boundary.

raw-sync clean-uploads runs one server-side cleanup pass for the PostgreSQL upload sessions and private spool used by agentsview replica pg serve:

agentsview source raw clean-uploads

The command uses the effective PostgreSQL target and AgentsView data directory from the current configuration. It can run while pg serve is stopped. Each pass uses the existing bound of up to 128 rows per SQL batch and 128 spool entries per directory scan. The command starts a fresh spool cursor on every invocation and inspects at most the first 128 entries in that scan window. Repeating the command can revisit the same preserved entries, so spool entries beyond that window require the long-running server, which keeps its cursor between the existing startup pass and its 15-minute cleanup passes. The command prints Raw upload cleanup pass completed. only after the pass succeeds. The PostgreSQL target must have the provisioned raw-sync schema and its write privileges. The command checks that capability before creating the upload spool.

agentsview why¶

Find recorded sessions and prompts behind a commit or file lines:

agentsview why internal/db/messages.go:120-140
agentsview why --commit 1a2b3c4
agentsview why main.go --format json

Use path:N for one line, path:N-M for an inclusive range, or path for the whole file. Line numbers start at 1. The file is blamed in its own Git repository, including when you run the command from another directory. Whitespace changes count, and uncommitted lines appear as a separate count. A file name ending in :digits is interpreted as a line range and can't be blamed by that name.

--commit accepts a SHA or prefix and works outside a checkout. Ambiguous prefixes return all recorded candidates. Add --format json or --json for scripts. Each commit keeps its own session links and the prompt before each commit call, even when one session made several commits.

The command calls no model. Run agentsview source sync first if you need newer records. A transcript link identifies the session that ran the commit; it doesn't prove who wrote each line. Deleted or trashed sessions appear as missing records without a prompt.

agentsview daemon¶

Manage the writable SQLite server. The daemon provides the web UI, API, session sync, and file watchers in one process. daemon start launches the same server as serve --background, using saved configuration and without opening a browser. It does not require a separate serve command. Unlike serve --background, which exits after daemon_idle_timeout when idle, daemon start stays running until daemon stop.

agentsview daemon start
agentsview daemon status
agentsview daemon restart
agentsview daemon stop

daemon start and daemon restart load the normal effective configuration from config.toml and supported environment variables. They accept no serve-specific flags: persistent daemon settings belong in configuration. --no-sync is runtime-only and is not a config.toml setting. Use agentsview serve --background --no-sync when a one-off detached server must disable sync. Similarly, use agentsview serve --background --host <address> for a one-off unauthenticated non-loopback bind; a persistent non-loopback host in config.toml requires require_auth = true.

These commands manage only the writable SQLite daemon for the current data directory, including a foreground serve process or a daemon auto-started by a CLI command. daemon stop stops the web UI and background sync together. They ignore read-only agentsview replica pg serve and agentsview replica duckdb serve processes. If only read-only servers are running, daemon status reports that no daemon is running, and daemon stop and daemon restart leave those servers alive.

Status distinguishes running, starting, and stopped states. daemon start returns after its initial readiness wait if a long migration or sync is still running; the child continues in the background. daemon restart stays attached and prints phase, detail, and elapsed-time updates until the replacement daemon is ready. Canceling that wait with Ctrl+C leaves the child running. Use agentsview daemon status and inspect the reported serve.log when startup is slow. If startup state remains stuck, follow the error's guidance to verify the owning process before terminating it manually and retrying.

Startup reports database opening, schema and index updates, and column migrations before that work begins. These steps appear in the terminal and serve.log, which also records their elapsed times. An upgrade that requires a full resync is announced as soon as the database version or schema check detects it. Session counters begin after database preparation finishes.

agentsview serve¶

Start the HTTP server with embedded web UI, session sync, and file watchers in the foreground. It remains attached to the terminal until you press Ctrl+C, unless --background is specified. This is the same writable server managed by agentsview daemon; the web UI and sync do not have separate lifecycles.

serve reuses or replaces an existing local writable daemon according to the replacement rules below. Read-only replica servers are left running. When reusing a server, serve reports its URL and exits with status 1 so systemd's Restart=on-failure retries; --background exits with status 0. Open that URL to use the web UI. Stopping the server with either daemon stop or serve stop also stops its sync and file watchers. --no-sync disables automatic sync in that process; it does not create a separate sync daemon. When an upgrade needs a full archive rebuild, --no-sync skips it at startup and says so. Until the rebuild runs, sessions that need the new parsers are missing. Click Sync in the web UI or run agentsview source sync to rebuild.

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.

The server auto-discovers an available port if the default 8080 or a port set in config.toml is busy. An explicit nonzero --port exits when that port is occupied. Use --port 0 to select any available port. For a supervised daemon that must keep a fixed port, pass --port in its launch command.

When replacing a running daemon, an occupied explicit port is rejected before the daemon stops. The daemon's existing host and port can be reused, including narrowing a wildcard bind to loopback. To widen a bind on the same explicit port, stop the daemon first with agentsview daemon stop.

agentsview update preserves the original --port choice recorded by the running daemon, including 0. Without an explicit port, restart tries the previous listening port and retains automatic fallback. 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 --background                   # start managed background server
agentsview serve --replace                      # replace an existing daemon
agentsview serve --public-url https://agents.example.com
agentsview serve --base-path /agentsview --public-url https://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 event batching; watcher sync starts remain at least five seconds apart by default; see sync_interval)
4. Starts periodic sync (every 15 minutes)
5. Serves the Svelte SPA and REST API

During a full parser or archive-only preservation rebuild, the daemon serves the retained archive with stale warnings. Archive writes return HTTP 503 with Retry-After; the CLI reports the server's message and exits. Scoped upgrades and schema repairs finish before the daemon listens.

CLI commands print one stale warning to stderr. The dashboard, MCP, and the X-Agentsview-Archive-Stale HTTP header also report stale results.

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

On current main, watcher batches link subagent relationships only for affected sessions. Unchanged polls skip archive-wide linking unless a failed or canceled batch left unfinished links. Poll logs identify the provider roots being checked and report how long the pass took.

During polling, changes to working-directory metadata refresh clients without triggering global parent linking. Worker processes return link repairs and unfinished linking to the daemon, so clients see repaired links and later polls retry failed linking even when an unrelated source cannot be processed. Workers confirm their link state separately from source errors, so completed repairs clear obsolete retries even when another source fails. Installed rebuilds also clear completed retries. Audit workers receive pending links from the daemon even when sources are unchanged. Missing or invalid worker results keep the retry pending. Startup transfers pending links before reconciling the worker-to-watcher gap. Repairs queued in the archive run even when discovery finds no source files. Repairs committed to the live archive refresh clients even if sync is canceled. Full resync aborts before replacing the archive if relinking copied sessions fails; discarded replacements do not report their repairs and preserve pending retries for the live archive.

Unchanged broken or missing source files are skipped through the failure cache described in Sync Behavior. Grok companion-file events use normal content-fingerprint checks, so repeated companion removal events do not clear a cached missing-summary failure. Actual companion edits still trigger sync.

Background Mode¶

The existing serve background and lifecycle forms remain available:

agentsview serve --background
agentsview serve status
agentsview serve restart
agentsview serve stop

The parent command starts a detached agentsview serve process and waits for it to publish its runtime record. The five-second readiness window measures startup inactivity, so continuing startup progress can keep the parent waiting longer. It then prints the URL, PID, and log path. Background server output is written to ~/.agentsview/serve.log. serve status reports the preferred managed process, URL, version, uptime, and read-only mode when available. For a writable server, serve status also asks for the Codex Cloud source's status. When the source is configured, it prints a status line for each ChatGPT account or Codex home, each followed by its live tokens and plan usage lines when they have something to report. When the source is off or its settings are wrong, it prints one status line for the whole source, followed by a "Live tokens: off." line. If the server cannot return the status, or fails while answering, serve status prints one line saying why, even when the source is not configured. Read-only servers, and older servers without this status, add no lines. serve stop retains its broad lifecycle scope: it gracefully terminates confirmed writable SQLite and read-only PostgreSQL or DuckDB server processes for the data directory and cleans up their runtime records.

serve restart is intentionally narrower and config-driven. It restarts only the writable SQLite daemon, leaves read-only servers alive, and starts the writable daemon if it was stopped. It accepts no serve flags and uses the same effective configuration as daemon restart. It is not equivalent to the broader serve stop followed by a foreground serve start.

serve and ordinary CLI commands automatically replace an older release daemon with a newer release. An older release reuses a compatible newer daemon; it does not downgrade it. When either binary is a development build, a different version string triggers replacement. Repeated dirty builds from the same commit can have the same version string and require agentsview daemon restart. Two different development installations sharing a data directory can replace each other when invoked; use separate data directories to keep them independent.

Long-running clients (mcp and push commands with --watch, including installed push services) start a missing daemon and reconnect after daemon restarts, but never replace a running daemon. They keep using it while its API and data versions are compatible. If incompatible, they report the conflict and ask you to restart the client with the current binary.

Use serve --replace or agentsview daemon restart for intentional replacement, including release downgrades. Automatic replacement preserves the daemon's launch options. All replacement paths check archive compatibility before stopping the daemon: an older binary cannot replace a daemon whose SQLite data version it cannot open. serve status reports incompatible live daemons with their daemon and binary versions plus daemon restart or daemon stop guidance.

Background servers also act as the shared local daemon for the desktop app and CLI. The daemon owns local SQLite writes for its data directory, so common write and freshness-sensitive commands proxy to it instead of opening the archive as a second writer. An automatically started daemon self-exits after the idle timeout when no external request or daemon-owned job is active. Periodic sync and file-watcher work prevent exit while they run, but do not keep the daemon alive forever by themselves.

sync_idle_after = "10m" pauses local collection while idle; "0" disables the pause.

CLI daemon behavior¶

Ordinary session commands, including session list, session get, and session messages, require a compatible local daemon and start one when needed. Use db adopt-machine --list to inspect historical machine keys or doctor sync for diagnostics. These dedicated commands read the archive without starting a daemon or changing configuration.

Commands that need fresh data or need to write auto-start the detached daemon when no compatible daemon is running. That includes local sync, session sync, token-use, normal usage refresh paths, pg push/pg push --watch, duckdb push, and clickhouse push. If a writable daemon is known to own the archive but is not reachable, these commands refuse instead of writing directly.

With --no-start-daemon, pg push --watch and clickhouse push --watch require an existing writable daemon.

Set AGENTSVIEW_NO_DAEMON=1 to disable daemon auto-start. Commands that require the daemon refuse while it is disabled. Direct write commands acquire the local write-owner lock before opening SQLite. If another process owns that lock, the command refuses. If agentsview daemon status shows a daemon, run agentsview daemon stop; otherwise find the agentsview process holding the lock file, then wait for it to finish or stop it. Auto-start (MCP and CLI commands that start a server on their own) reports the holder in the same way instead of launching a server that could not open the archive. daemon start and serve --background report the child's failure as before.

agentsview source sync¶

Refresh the local archive. For local sync, the CLI uses the running daemon or starts a detached daemon so SQLite writes stay owned by one process. That daemon also serves the web UI and remains running after the CLI exits, until stopped or its idle timeout expires. The command prints the server URL and how to stop it.

An incremental local-only sync through the default daemon waits when another sync or maintenance pass owns it, then runs its requested pass. It prints waiting status; Ctrl+C cancels the wait without stopping the existing work. This waiting message applies when no remote hosts are configured. Full resync, syncs that include remote hosts, and servers started with --no-sync also wait for exclusive access, but do not show this message. If the wait persists, inspect agentsview daemon status and serve.log. A daemon launched for this local sync skips its redundant startup sync.

For a one-shot offline sync, stop the writable daemon first, then run:

agentsview daemon stop
AGENTSVIEW_NO_DAEMON=1 agentsview source sync

The environment variable disables daemon auto-start. It does not stop an existing daemon or bypass its write-owner lock. The offline command acquires that lock, syncs directly, and exits without leaving a server running.

agentsview source sync [flags]

Examples:

agentsview source sync           # incremental sync and exit
agentsview source sync --full    # full resync and exit
agentsview source sync --target /path/to/shared-folder
agentsview source sync --host devbox1

After syncing, a summary of session and message counts is printed to stdout. With --target, AgentsView then performs one bounded normalized-artifact exchange. See Artifact Folder Sync for the trust model, first-use requirements, and exclusions. --target cannot be combined with --host.

When --host is set, AgentsView syncs only the matching configured [[remote_hosts]] entry and fails fast on error. This also applies to offline sync with AGENTSVIEW_NO_DAEMON=1: the local command contacts the configured remote directly. Unknown host names are rejected; ad hoc remotes are not supported. --host runs an entry with transport = "ssh" the same way as an HTTP entry; see SSH Remote Sync.

Local sync can also read configured Claude, Codex, and Cursor roots from S3-compatible object storage. Add s3:// entries to agents.claude.dirs, agents.codex.dirs, or agents.cursor.dirs in ~/.agentsview/config.toml, then run agentsview source sync normally. Object storage is treated as a read-only session source, using object size and LastModified metadata to skip unchanged sessions and downloading only objects that need parsing. See Configuration — S3-Compatible Session Sources.

Configured Remote Hosts¶

Declare remote hosts in ~/.agentsview/config.toml so a single bare agentsview source sync covers a whole fleet. An entry uses transport = "http" (the default) to reach a remote daemon, or transport = "ssh" to reach a machine over ssh with no AgentsView running there:

[[remote_hosts]]
host = "devbox1"
transport = "http" # optional; default
url = "http://devbox1.tailnet.ts.net:8080"
token = "remote-token"

[[remote_hosts]]
host = "devbox2"
transport = "ssh"
destination = "[email protected]" # optional; defaults to host

With hosts configured, agentsview source sync (no --host) includes local sources and configured hosts, HTTP and SSH, in one coordinated sync. During a full or automatic data-version rebuild, AgentsView prepares every remote mirror, bulk-ingests the local and remote sources into one temporary database with FTS updates suspended, rebuilds FTS once, and atomically swaps the completed archive into place.

--full reparses every discovered local and remote session, but it does not force unchanged manifest-capable files to transfer again. Directory-scoped and verbatim curated content still use delta transfer. Windsurf's sanitized curated export remains a separate full-archive transfer on every sync. HTTP collectors and spokes must use the same remote-sync protocol version; incompatible peers fail before exchanging targets or archive data. A configured HTTP host that is offline, cannot resolve through DNS, is unreachable, or times out is skipped; an SSH host is skipped when ssh reports one of the network errors listed under Offline Hosts. Local sources and reachable hosts still join the combined rebuild. Archived sessions from skipped hosts are preserved. Other remote preparation or contributor failures abort the combined rebuild without replacing the active archive. The command exits non-zero for any failure other than an unavailable configured host. See Incremental Sync.

HTTP remote sync requires a reachable remote daemon, preferably over a private network such as Tailscale, and remote archive endpoints always require bearer auth. Every host requires a url and a token matching the remote daemon's auth_token; do not reuse the collector daemon's own token for untrusted remote endpoints. Ad hoc HTTP remotes are not supported. Hosts must be unique within the list, since remote sessions are namespaced by host.

During HTTP remote sync, the collector prints durable phase lines for resolving remote roots, fetching and comparing the manifest, transferring and extracting changed files, planning pending paths, processing affected sources, rebuilding FTS, and swapping the database. Pending paths can outnumber processed sources: deletions participate in recovery and cache invalidation but usually do not produce an import source. Provider fallback is identified explicitly, and its discovered sources determine the processing denominator.

The final per-host line reports changed sessions, ordinary unchanged skips, and error-suppressed pending entries. A retained-journal line means recovery work will be replayed; cancellation, processing failure, cache-persistence failure, retirement failure, and a rebuild awaiting its database swap remain distinct. Individual source paths are omitted from normal output. Archive downloads also show live compressed-byte progress when the remote daemon provides a Content-Length header. These phases come from the collector; a spoke upgrade is needed only for manifest-delta transfer. If an upgraded binary does not show them, restart the local collector daemon.

agentsview session prune¶

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

agentsview session prune [flags]

Filters combine with AND. With --agent, one prune removes matching parents and descendants, including matching sessions in trash. A descendant that fails any filter keeps all its ancestors. Without --agent, prune skips trash and parents. The summary shows how many matches are in trash.

Prune keeps deleted sessions out of later syncs. To keep new sessions from that agent out of the archive, add it to disabled_agents.

Examples:

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

# Preview cleanup of an agent after stopping the daemon
agentsview session prune --agent mimocode --dry-run

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

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

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

Prune deletes each matching session's source file, except the shared state.db of apps such as Hermes and Augure Desktop, which stays in place. The summary reports sessions deleted, disk space reclaimed, and how many source files stay in place. Use --dry-run first to preview the matches.

agentsview db adopt-machine¶

Assign historical local machine keys to this installation. Use this when an upgrade could not establish which archived sessions are local, or to adopt additional old hostnames you own. Inspect the archive first, then stop the daemon:

agentsview db adopt-machine --list
agentsview daemon stop
agentsview db adopt-machine host-a.example host-b.example
agentsview daemon start

Use --list alone to print machine keys with session and worktree-rule counts. It does not start a daemon, write configuration, or adopt sessions.

Select only keys whose sessions belong to this installation. The command moves their sessions, worktree rules, and project and source metadata to the current installation ID. Session IDs, messages, stars, pins, and other curation stay intact. Old named keys remain aliases for filters and URLs. Conflicting worktree rules stop the command so you can reconcile them before retrying.

Keys that belong to other installations need no action. Legacy local rows always belong to this archive and are assigned to its installation ID at startup.

The command records ownership in the archive; changing local_machine_name only changes a display label. See Upgrading Historical Machine Keys for automatic adoption and mirror updates.

agentsview db repair-projects¶

Available in 0.47.0 and later. Preview corrections for temporary worktree project names using repository URLs already saved in the archive:

agentsview db repair-projects
agentsview db repair-projects --project sample_feature --format json
agentsview db repair-projects --project sample_feature --apply

The default is read-only. --project selects an exact current project label; omit it to examine all projects. --apply requires exclusive archive access, so stop the daemon or desktop app first. JSON output includes each repository, old and new project names, reason, session count, and the number of sessions left unresolved because checkout names conflict. See repair worktree project names for the naming rules and preservation guarantees.

agentsview db compact¶

Reclaim unused space in the local SQLite archive. The command writes and checks a compacted database before replacing the original, and truncates the write-ahead log (WAL). It preserves stored sessions and does not change what future imports retain.

agentsview db compact [flags]

JSON mode writes only the final result to stdout and requires --yes; prompts and human progress messages are written to stderr. When a writable daemon owns the archive, --staging-dir is not accepted because the daemon chooses its own staging location and the compact endpoint is restricted to localhost. The command probes for an existing daemon and never starts one: maintenance must not trigger a daemon's startup sync. When no daemon owns the archive, the command takes the direct write lock and compacts in process.

On a shared filesystem, peak additional space includes the original backup, the compacted candidate, a second candidate copy beside the live database, and a safety margin. With separate filesystems, staging needs the backup plus one candidate and the database filesystem needs the installation copy. The live source remains present until the final rename and is never credited as free space. For a large archive, use a separate volume with enough capacity:

agentsview db compact --dry-run
agentsview daemon stop  # required for --staging-dir
agentsview db compact \
  --staging-dir /mnt/cache/data-cache/agentsview-compact \
  --keep-backup --yes
agentsview daemon start

When a writable daemon is running, the command sends the request to that daemon. Direct file access is refused while another daemon owns the archive. Reads continue during the staged build, while writes are refused with a retryable archive-maintenance error until the verified replacement is committed; connections pause only for the final swap. Compactions are serialized per archive: a compaction requested while a sync, resync, or another compaction is running fails immediately with a conflict instead of queueing.

If a compaction is interrupted or fails partway, the archive stays safe: a recovery manifest (compact-recovery.json beside the database) records the operation, and the next writable start finishes or rolls back the replacement before the archive opens. Until then the daemon may keep refusing writes and the error names the manifest; restarting the daemon resolves it. Once a compaction has committed, recovery only cleans up leftover staging files and never replaces the archive, so sessions ingested after a compaction are never at risk. Do not delete the manifest or the database files by hand.

agentsview db strip --images¶

Replace supported inline images and offloaded image references in stored tool results with text descriptions. The command requires --images and asks for confirmation. It never changes provider source files or standalone image files. Run db compact separately when you need measured SQLite file-space reclamation. Changed sessions are automatically rescanned for secrets so detections reflect the remaining content.

Preview with --dry-run. Before applying changes, run agentsview daemon stop. The CLI writes directly to the archive and refuses while a writable daemon owns it. It does not start a daemon. Restart the daemon after the command finishes.

agentsview db strip --images [flags]

JSON apply requires --yes. Preview and a declined confirmation leave the archive unchanged. Reported stored-content bytes and decoded image bytes are content measurements, not reclaimed disk space.

agentsview db migrate --images¶

Move retained inline tool-result image payloads from currently stored archive rows into the asset store at {dataDir}/assets. Each payload is written as a content-addressed file named <sha256hex><ext>. Before the row changes, an existing object must have the expected byte count and SHA-256 digest. A missing or corrupt object is replaced while the source bytes remain available. The inline input_image block is replaced with an agentsview_image placeholder whose image_ref field holds the asset:// reference. The GET /api/v1/assets/{filename} route and renderMarkdown resolve these references from the local assets directory.

The image appears in formatted tool output alongside text and other supported inline or offloaded images. Raw mode shows the stored text, including the markdown reference, as it always has, and so does a result that still holds an unmigrated image block, such as an SVG or an image/bmp payload beside a migrated PNG. Under require_auth the asset route rejects the browser's image request, because an img element sends no Authorization header. Chat-imported images already carry that limit.

Migration updates images already in the archive. Set tool_result_images = "offload" and restart the daemon to store future supported images in the same asset directory. With keep, a later reparse or full resync can restore inline images from provider source files. With drop, ingestion and full resync replace images with text descriptions. db strip --images also removes offloaded references from selected results. Neither operation deletes asset files. The migration command requires --images and never changes provider source files. A separate serving host needs the matching {dataDir}/assets directory as well as the copied database content. Run db compact separately to measure SQLite file-space reclamation after migration. Back up the {dataDir}/assets directory together with the archive.

The raw agentsview session export command still streams provider source bytes. See image storage for export and remote-backend limits.

If a session transaction fails after writing assets, its rows remain unchanged but complete, unreferenced asset files remain on disk. Retrying the migration reuses matching files; there is no automatic cleanup of unreferenced assets. Both db migrate --images and db strip --images report the sessions that committed before a later failure.

JPEG assets now use .jpg filenames, including .jpeg files copied from chat imports. Existing asset://<hash>.jpeg references still resolve, but re-importing an export with those files can create a second copy under .jpg.

Only the four passive image media types are migrated: image/png, image/jpeg, image/webp, image/gif. Every other payload stays inline, including SVG, which the serving route refuses as active content, and near-misses such as the non-canonical image/jpg spelling. db strip --images is broader and replaces any image/* payload with a placeholder, so the two commands do not select the same rows.

Preview with --dry-run. Before applying changes, run agentsview daemon stop. The CLI writes directly to the archive and refuses while a writable daemon owns it. It does not start a daemon. Restart the daemon after the command finishes.

agentsview db migrate --images --dry-run
agentsview daemon stop
agentsview db migrate --images
agentsview daemon start

JSON apply requires --yes. Preview and a declined confirmation leave the archive and assets directory unchanged. Reported stored-content bytes and decoded image bytes are content measurements, not reclaimed disk space.

agentsview version¶

Print the version, git commit, and build date. Use --json for a stable, machine-readable response that does not require a running daemon, configuration, or database.

agentsview version
agentsview version --json
agentsview version --format json

agentsview v0.38.0 (commit 5b42bf1c, built 2026-07-13T15:37:17Z)

{
  "schema_version": 1,
  "name": "agentsview",
  "version": "v0.38.0",
  "commit": "5b42bf1c",
  "build_date": "2026-07-13T15:37:17Z"
}

The JSON contract uses these fields:

Consumers should require the expected schema_version and ignore unknown fields. Adding an optional field does not require a schema bump; removing or renaming a field, changing a field's type or meaning, or making a previously valid response invalid does.

agentsview source list¶

List every agent AgentsView can read, where it looks for each agent's sessions, and which session details each agent's parser extracts. Pass one or more agent types to show only those agents. The command does not need a running daemon, configuration, or database.

agentsview source list
agentsview source list codex claude
agentsview source list --json

codex (Codex)
  sessions: ~/.codex/sessions, ~/.codex/archived_sessions
  override: CODEX_SESSIONS_DIR
  reads: first_message, session_name, cwd, git_branch, relationships, subagents, thinking, tool_calls, tool_results, tool_result_events, per_message_token_usage, termination_status, model

The sessions line shows the default locations relative to your home directory. The override line names the environment variable that replaces them. Import-only agents show imported with agentsview source import instead.

The JSON contract has schema_version (currently 1) and an agents array. Each agent has these fields:

New content details may appear without a schema bump, so consumers should ignore names they do not recognize.

agentsview report 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 on reporting behavior and agent coverage.

The report reads committed archive data. If it starts the daemon, session sync runs in the background; run agentsview source sync first when new source changes must be included. An older archive that requires reparsing is upgraded before the daemon starts serving, with startup progress shown in the terminal. A cold usage cache prepares the sessions needed for the report without waiting for the full archive backfill. Slow reports print the current preparation phase and elapsed time to stderr, including with --json. Usage preparation is not subject to the server's normal write timeout. Press Ctrl+C to stop waiting; shared cache work can continue in the daemon.

Restart older daemons after upgrading so they provide the usage progress endpoint. usage statusline still waits for initial sync, including when it reuses a daemon started by daily usage. Statusline limits the complete wait and report request to 30 seconds.

Offline reads require an archive at the current data version. If an upgrade requires a resync, run agentsview daemon restart and let the resync finish before retrying the offline command.

agentsview report usage daily [flags]

When the window includes Codex Cloud sessions that have only plan usage, the report leaves them out of the totals and prints "note: N sessions billed as plan usage, not priced, are left out of these totals." Sessions whose turns were captured only in part add a second note that their token counts are low. With --json, the counts are planOnlySessions and partlyCapturedSessions.

Examples:

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

agentsview report usage statusline¶

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

agentsview report usage statusline [flags]

Example:

$ agentsview report usage statusline
$9.61 today

$ agentsview report usage statusline --json
{
  "date": "2026-08-04",
  "cost": {
    "microdollars": 9610000
  }
}

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

agentsview source cursor sync-usage¶

Fetch Cursor Admin API usage events and store them in the local archive so they contribute to the Usage dashboard and daily reports.

agentsview source cursor sync-usage [flags]

Examples:

agentsview source cursor sync-usage
agentsview source cursor sync-usage --since 2026-05-01 --until 2026-05-31
agentsview source cursor sync-usage --all --email [email protected]

See Cursor Admin Usage Events for setup and reporting behavior.

agentsview report activity¶

Report active time, concurrency, cost, token, breakdown, and session rows for a resolved date range. The command uses the same report model as the web UI's Activity page.

agentsview report activity [flags]

Examples:

agentsview report activity --preset day --date 2026-06-20
agentsview report activity --preset week --date 2026-06-20 --json
agentsview report activity --preset custom \
  --from 2026-06-20T14:00:00Z \
  --to 2026-06-20T18:00:00Z \
  --bucket 15m

The human output prints totals, peak concurrency, top project/model/ agent breakdowns, and top sessions. JSON output includes the dense bucket timeline and session rows used by the web UI.

agentsview token-use¶

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.

The command uses a compatible local daemon, starting one if needed. It follows the same refresh and missing-session behavior as agentsview session usage.

Totals include archived subagent spend. token-use has no opt-out; use agentsview session usage <id> --own-only for own-session numbers.

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

cost_usd is a deprecated compatibility alias for cost.microdollars / 1e6 and will be removed in a future release; new consumers should read cost.microdollars directly.

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

agentsview replica pg push¶

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

agentsview replica pg push [target] [flags]

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

--embed pushes sessions first, then builds and pushes embeddings in the same push, using [vector] or a recipe published to PostgreSQL. --full --embed repairs vector rows too. Watch mode builds in the background after each sync that commits changes and pushes built vectors on the next interval. It never starts a daemon and refuses to run while one owns the archive. It cannot be combined with --no-vectors, --all, or a target with push_vectors = false. See Build and push embeddings in a container.

agentsview replica pg status¶

Show PostgreSQL sync status.

agentsview replica pg status [target] [flags]

agentsview replica pg serve¶

Start a read-only session web UI backed by PostgreSQL. On a writable PostgreSQL schema, the same server also registers the hosted raw-sync control plane. See PostgreSQL Sync for full server documentation.

agentsview replica pg serve [flags]

agentsview replica pg serve --push-watch

Use --push-watch to ingest mounted sessions and publish them in the same process; see PostgreSQL Sync for setup and shutdown.

Accepts the same serve flags (--host, --port, --proxy, etc.) plus PostgreSQL configuration from config.toml. When the host's [vector] config matches a generation pushed to PostgreSQL, semantic and hybrid search are served from pgvector — see Semantic Search — PostgreSQL.

agentsview replica pg service¶

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

Use service install --no-start-daemon with your own collector. The push service exits if no writable daemon is running, and the service manager restarts it until the collector answers. Reinstalling restarts the service with the new arguments. The default installation still starts a missing daemon. Reinstalling without --no-start-daemon restores daemon autostart.

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

agentsview replica pg vectors¶

Inspect and drop semantic-search embedding generations stored in PostgreSQL. See Semantic Search — Maintenance for details.

agentsview replica pg vectors list [flags]
agentsview replica pg vectors drop <id> [flags]

agentsview replica duckdb¶

Mirror the local SQLite archive into DuckDB and serve from it, locally or over the Quack remote protocol. See DuckDB Mirror for full documentation.

agentsview replica duckdb push          # mirror SQLite into sessions.duckdb
agentsview replica duckdb status        # show mirror sync status
agentsview replica duckdb serve         # read-only web UI from the mirror
agentsview replica duckdb quack serve   # expose the mirror over Quack

duckdb push accepts the same --full / --projects / --exclude-projects / --all-projects / --watch / --debounce / --interval flags as pg push. duckdb push always writes the local mirror file at [duckdb].path; it never targets a remote Quack endpoint. If [duckdb].url or AGENTSVIEW_DUCKDB_URL is configured, push fails immediately with an error to unset it and serve the mirror remotely with duckdb quack serve instead. duckdb status and duckdb serve do target the remote Quack endpoint when [duckdb].url or AGENTSVIEW_DUCKDB_URL is set, and the local mirror file otherwise. When [duckdb].path or AGENTSVIEW_DUCKDB_PATH is set, duckdb quack serve exposes that same mirror by default unless --path overrides it. duckdb serve accepts the same serve flags as pg serve. The DuckDB backend is unavailable on Windows ARM64 (the upstream bindings ship no prebuilt library for that platform); all other commands work normally there.

agentsview replica clickhouse¶

Push the local SQLite archive into ClickHouse and serve the read-only web UI from it. See ClickHouse Sync for full documentation.

agentsview replica clickhouse push [target] [flags]
agentsview replica clickhouse status [target] [flags]
agentsview replica clickhouse serve [flags]
agentsview replica clickhouse service install

clickhouse push accepts the same --full / --projects / --exclude-projects / --all-projects / --all / --watch / --debounce / --interval flags as pg push, except there is no --no-vectors flag. ClickHouse has no vector phase. --all --watch is rejected.

clickhouse serve accepts the same serve flags as pg serve. clickhouse service installs clickhouse push --watch as a launchd or systemd user unit and writes clickhouse-watch.log. Use clickhouse service install --no-start-daemon with your own collector.

agentsview project list¶

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

agentsview project list [flags]

Examples:

agentsview project list         # tabular output
agentsview project list --json   # JSON array

agentsview session health¶

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

agentsview session health [session-id] [flags]

Examples:

agentsview session health
agentsview session health --limit 50
agentsview session health 550e8400-e29b-41d4-a716-446655440000
agentsview session 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 report stats¶

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

agentsview report stats [flags]

Examples:

agentsview report stats
agentsview report stats --format json --since 2026-04-01 --until 2026-04-15
agentsview report 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 doctor sync¶

Collect read-only diagnostics for startup sync decisions. This command does not create or migrate config files; it loads the current config read-only, inspects the SQLite archive, checks configured agent roots, and prints recent sync-related debug.log lines.

If startup has rotated the log, inspect debug.log.1 in the data directory for the previous tail.

agentsview doctor sync

The report includes:

• data directory and SQLite database path
• whether the database exists and is readable
• SQLite user_version and the binary data version
• the startup sync decision
• session counts by stored data version
• leftover resync temp files
• configured/default agent roots and whether each exists
• recent debug lines mentioning sync, data versions, warnings, or failures
• Antigravity CLI summary-mode counts and Antigravity sessions decoded from unrecognized agy-schema: fingerprints
• a likely-cause summary when startup sync behavior looks abnormal

agentsview archive diff¶

Validate parser changes against the real session archive already in your local SQLite database. The command re-parses source files with the current binary, normalizes them through the sync path, and reports field-level differences from the stored rows without writing updated session data.

agentsview archive diff [flags]

Examples:

agentsview archive diff --agent claude --limit 100
agentsview archive diff --agent codex --fail-on-change
agentsview archive diff --json > parser-report.json

parse-diff is intended for parser development and release QA. Run it against a quiescent, freshly synced archive for the clearest signal. Import-only sources are skipped because there is no source file to re-parse. Provider-backed stores with authoritative local sources, including Warp, Forge, Piebald, and Devin, are covered alongside normal file-backed agents.

The report distinguishes parser drift from comparison-basis skew:

• raced means the source changed while parse-diff was running. It is reported for review but does not fail --fail-on-change.
• incremental_skew means the stored row was last written by an incremental-append sync, so a fresh full re-parse can legitimately differ on append-path metadata. It is also reported but excluded from --fail-on-change.
• pending_resync means the stored data version is behind the running binary; sync reparses available stale sources, rebuilding the archive when required.

If the report includes incremental_skew, run a full resync before treating the archive as a clean parser-drift baseline. A full resync rewrites those rows through the normalization path and restores strict parse-diff scrutiny.

agentsview source chrome setup¶

Install the native host and unpacked extension for Claude.ai Sync through Google Chrome. The command prints the extension folder. AgentsView opens its Chrome connection only after setup, so restart AgentsView if it is already running. Open chrome://extensions, enable Developer mode, choose Load unpacked, and select that folder. Keep Chrome open during Sync. Registration is per OS user; the last setup wins. The first connected Chrome profile is used. Rerun setup and reload the extension when the executable path or data directory changes. After an upgrade mismatch, restart AgentsView if you upgraded it, rerun setup, reload the extension at chrome://extensions, then Sync again.

See Sync Claude.ai chats for connection and removal instructions.

agentsview source import¶

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

agentsview source import --type <type> <path>

Set up the Chrome host once and keep Chrome open for agentsview source import --type claude-ai --sync.

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

Examples:

agentsview source import --type claude-ai ~/Downloads/claude.zip
agentsview source import --type chatgpt ~/Downloads/chatgpt.zip
agentsview source import --type claude-ai ./conversations.json
agentsview source import --type gemini-apps ~/Downloads/takeout.zip
agentsview source import --type chatgpt --replace 'chatgpt:<conversation-id>' ~/Downloads/chatgpt.zip

agentsview export sessions¶

Export content-free session summaries from the local archive. See Session Export for the full JSON/NDJSON contract, cursor semantics, pricing provenance, and project identity rules.

agentsview export sessions [flags]

By default, one-shot and automated sessions are excluded, so token and cost totals can be lower than the full archive unless the corresponding include flags are used.

Examples:

agentsview export sessions --format json
agentsview export sessions --format ndjson --limit 100
agentsview export sessions --all --format ndjson --project agentsview

The JSON top level has schema_version, archive_id, database_id, cursor, pricing, projects, and sessions. NDJSON writes the same metadata as the first line, then one session row per following line. Current builds emit schema_version: 6; see Session Export for the v1 and transitional 0.38 release history. The default and maximum page size is db.MaxSessionLimit, currently 500.

For performance diagnosis, export sessions, export hour, export day, and export digest accept --cpuprofile <file>, --memprofile <file>, and --trace <file>. These write profiling data to files and keep the export on stdout.

When --cursor is present, only --format, --json, --limit, and the profiling flags may be combined with it. Cursor reset errors write structured JSON to stderr, leave stdout empty, and exit with code 4:

{"error":"cursor_reset","message":"session export cursor is no longer valid; restart the export","database_id":"..."}

agentsview export conversations¶

List conversation changes without message text, then fetch selected visible user/assistant messages in bounded chunks. See Conversation Export for identity, content, checkpoint and coverage rules.

agentsview export conversations changes
agentsview export conversations changes --checkpoint SAVED_CHECKPOINT
agentsview export conversations message SESSION_ID MESSAGE_ID \
  --database-id DATABASE_ID --revision REVISION

These commands read the local archive and do not send content to another system. Existing session summary and activity exports remain content-free.

agentsview export hour|day|digest|range¶

Export hourly activity and usage, complete days, or digests that identify changed hours from the local SQLite archive. A digest is a checksum of the exported content. See Reporting Export for the JSON fields, version rules, and correction workflow.

agentsview export range
agentsview export hour 2026-07-28-13
agentsview export day 2026-07-28
agentsview export day --schema-version 5 --bucket 1m 2026-07-28
agentsview export day --schema-version 5 --by-machine 2026-07-28
agentsview export digest --from 2026-06-28 --to 2026-07-27

Hour and date keys must be exact, zero-padded UTC values. Open and future hours are rejected. The current UTC date contains only closed hours and has no day digest. Digest ranges include both dates and are limited to 31 days.

Version 3 is the default. Use --schema-version 5 to group activity and usage by project, agent, model, and activity category together. Version 5 keeps repositories that share a project name separate. It also accepts repeatable --project-key filters and a --bucket duration, such as 1m, 5m, or 15m. The duration must be a positive whole-minute divisor of one hour. Version 3 rejects both options. Versions 1, 2, and 4 are no longer available. Validate your chosen schema_version and content digest before accepting a document. Refresh saved digests when changing versions.

agentsview session¶

Machine filters accept exact IDs, aliases, comma-separated ID/alias lists, or a unique whole display label. A valid 32-hex installation ID takes precedence even without stored sessions. Unknown or ambiguous names return an error with choices.

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 list --resume         # recently-active resume table
agentsview session messages <id>         # paginated messages
agentsview session commits <id>          # commits and their prompts
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 diagnose <id> --format json  # archived usage and diagnostic evidence
agentsview session usage <id>            # token usage and cost estimate
agentsview session usage <id> --own-only # exclude subagent transcripts
agentsview session usage-batch <id>...   # ordered usage results for several sessions
agentsview session label <id> k=v ...    # add or remove labels
agentsview session parent <id> <parent>  # record the launching session

agentsview session commits <id> lists transcript and Git trailer commits linked to a session. The SOURCE column distinguishes transcript from commit message. JSON keeps source: "trailer" for commit message links. Use --format json for structured output. The table shows the session, exact message ordinal, call time, source, recorded SHA, branch, subject, and user turn, shortened to 100 terminal columns. Transcript links use the last real prompt before the commit call. Trailer links use the last real prompt at or before Git's author time and mark the turn as estimated. They require a session message within the five minutes before that time; an idle session has no suggested turn. The prompt can be older than five minutes when later messages keep the session active. Trashed or permanently deleted sessions carry missing: true and omit the turn. See commit lookups for retention and lookup limits. Transcript links require stored Git summaries with SHAs of 7 to 64 characters. Quiet commits have no transcript link. Links include Codex poll results paired with the original call. Calls spanning repositories use the first directory; the last cd before the first commit invocation adjusts it. Archives retaining only transcripts keep trailer links; usage-only archives have no links. Hosted PostgreSQL returns HTTP 501. Sessions permanently deleted before this release have no transcript links. JSON output keeps call_index. Code-mode scripts with exactly one tool call and a fixed command literal can link commits, including output without a process ID. Command literals containing ${ have no links. A single-call write_stdin script can poll an earlier commit execution. Scripts with several tool calls cannot start new commit links; their polls need output process IDs matching an earlier commit call.

session list --label k=v and --pr owner/repo#123 filter by labels and pull request links.

session usage includes archived subagent spend in the parent total. See the session usage contract for refresh behavior, missing-session exit codes, and the refresh_incomplete JSON field.

An empty first page of session search keeps (no matches) on stdout and prints measured hints on stderr when one-shot, automated, or child sessions contain matches. Each hint includes a command that preserves your filters and enables the required include flags. JSON adds hints entries with code, message, and a full next command. Counts use a bounded search and say more than N when more matches exist, or at least N for semantic and hybrid searches or when filtering or candidate limits prevent an exact count. For multi-word substring queries over messages, a hint offers --fts only when that retry finds matches. excluded_combined gives a retry with the remaining include flags for matches beyond the individual class hints. Failed diagnostic searches add no hint.

session search supports substring (default), --regex, --fts, --semantic, and --hybrid modes. Repeatable --exclude-session <id> drops matches from those sessions before --limit. Hybrid returns keyword matches with a note while the embedding index is unavailable. Semantic and hybrid results can be scoped with --scope top|all|subordinate (default all) to include or exclude sidechain and subagent content — see Semantic Search. HTTP and MCP also accept scope for substring and regex searches. CLI lexical searches use --include-children instead. The human-readable table includes an AGE column derived from each match's timestamp, so recent evidence is visible without opening the session. Matches without a usable timestamp show —.

Structured response commands accept --format json; --json is a short alias for that scripting mode. session export and session watch are the exceptions: they stream raw bytes and NDJSON respectively, so they reject --format/--json. Use --server <url> to target an explicit running daemon, AGENTSVIEW_SERVER_TOKEN or --server-token-file <path> when that daemon requires auth, or --pg to read from configured PostgreSQL.

agentsview session list excludes one-shot, automated, and child sessions by default. When that hides matching sessions on the first page, it reports the counts and the corresponding --include-one-shot, --include-automated, or --include-children flags on stderr, including when the list has visible results. Child counts include sessions hidden by several defaults; the notice lists every remaining include flag to use together. Child counts use one bounded page; a positive count from a partial page says at least N. Stdout, including --format json, keeps its existing shape for pipelines.

An older daemon can return sessions without exclusion counts. The CLI lists those sessions and omits the exclusion notice. Cursor pages and lists with all three --include-* flags also omit the notice.

AGENTSVIEW_PG_URL, a legacy [pg].url, or the effective default target from default_pg plus [pg.NAME] are sync configuration only; they do not change the default read path. Read commands use local SQLite unless --pg is supplied, in which case they fail fast if no connection URL is available. Mutating commands such as session sync and local-only raw source export continue to use the local archive.

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

agentsview session list renders a resume-oriented human table by default, including a recently-active marker, session ID, age, agent, project, branch, message count, title, and working directory. Pass --resume or its --active alias to show sessions active in the last 15 minutes; combine either flag with --active-since <RFC3339> to choose a wider or narrower window.

agentsview index embeddings¶

Manage the local semantic search embedding index. Requires [vector] to be enabled in config. See Semantic Search for full documentation, including configuration and the search surface.

agentsview index embeddings build           # build or refresh the index
agentsview index embeddings list            # list embedding generations
agentsview index embeddings activate <id>   # activate a generation
agentsview index embeddings retire <id>     # retire a generation

agentsview recall¶

Inspect the experimental durable-knowledge layer over the local session archive. Recall is active research and its corpus may require rebuilding as the schema, scoring, and trust policy evolve. See Recall (Experimental) for its current guarantees and limitations.

agentsview recall list
agentsview recall get <id>
agentsview recall query <text>
agentsview recall brief <task>
agentsview recall stats
agentsview recall extract run [--session <id>] [--full] [--limit <n>]
agentsview recall extract status
agentsview recall extract activate
agentsview recall extract retire <fingerprint> [--force]
agentsview recall extract doctor
agentsview recall extract preview --session <id>
agentsview recall import <accepted-recall.jsonl> --dry-run

Model-backed extraction requires an enabled [recall.extract] config section — see Recall. preview replaces the earlier extract --session <id> --dry-run form, which still works as a fallback. The extraction subcommands operate on the local archive only and refuse --server; while a daemon owns the archive, it runs extraction passes itself and manual run/activate/retire are refused.

Use an isolated AGENTSVIEW_DATA_DIR for Recall population experiments. Import with --dry-run first; a write requires --yes, and a remote write also requires --allow-remote-import. Import against the default production directory is refused unless --allow-production-import is supplied explicitly. These flags do not bypass Recall's trust or evidence checks.

When --server <url> targets an explicit daemon, provide remote credentials with AGENTSVIEW_SERVER_TOKEN or --server-token-file <path>. Recall never sends the local daemon token from config.toml to an explicitly supplied server.

agentsview kata status¶

Shows whether the configured Kata instance is reachable, compatible (API schema 0.21.0 or newer), authenticated, and has the configured project. With a running daemon it reports the daemon's view. When no daemon owns the data directory, it probes from the local config without starting one. An unreachable owner returns an error. --format json prints the status object; --json is an alias. --format human selects the default text output. --server URL asks an explicit AgentsView daemon; use AGENTSVIEW_SERVER_TOKEN or --server-token-file PATH for its credential. See Kata.

agentsview insight¶

Generate and inspect stored Activity Insights through the daemon API.

agentsview insight list [--type <type>] [--project <project>] \
  [--date-from <date>] [--date-to <date>]
agentsview insight get <id>
agentsview insight generate --type daily_activity --date-from <date> \
  --date-to <date> [flags]
agentsview insight generate --type tool_effectiveness --session-id <id>

insight list accepts --type, --project, --date-from, and --date-to. insight get prints one saved insight. Use --format json or --json for the API envelope and complete stored rows. Human output prints a table for list and the saved Markdown content for get.

insight generate accepts --type, --date-from, --date-to, --project, --prompt, --session-id, --agent, --automated-scope, and --timezone. The type defaults to daily_activity. The server validates fields, selects the configured agent or endpoint, and decides whether the selected backend can save the result. Local commands discover or start the configured daemon; an explicit --server <url> targets an already running server.

Use tool_effectiveness with --session-id to assess one session's tool calls. The saved report marks conclusions as helped, did not help, or unclear and cites the calls behind them. See Tool effectiveness reports for the input limits and what is sent to the configured model.

Generation status and log events go to stderr. The saved insight is the only result written to stdout, which keeps JSON output usable in scripts. For an explicit server, provide its bearer token with AGENTSVIEW_SERVER_TOKEN or --server-token-file <path>. The local daemon token from config.toml is never sent to an explicitly supplied server.

agentsview doctor memory¶

Inspect the selected conversation-memory target and the local client package:

agentsview doctor memory
agentsview doctor memory --server <url> [--server-token-file <path>]
agentsview doctor memory --pg
agentsview doctor memory --plugin-root <path> --format json

The target section uses the same readiness provider as MCP get_memory_status and search-result coverage. It reports the authenticated archive identity, backend, read-only mode, lexical availability, semantic generation coverage, source telemetry, and server version when available. An older remote server reports unknown with reason unsupported; authentication and transport failures remain command errors instead of looking like an empty archive.

The client section checks the native package's recall skill, focused MCP configuration, and SessionStart hook when --plugin-root, PLUGIN_ROOT, or CLAUDE_PLUGIN_ROOT identifies the package. It also detects standalone AgentsView skills and reports when their baked target differs from the selected archive. Human and JSON output omit plugin paths, server URLs, and token values.

Local diagnostics open the archive read-only and do not start a daemon. Every mode is metadata-only: the command does not sync transcripts, rebuild vectors, probe an embedding provider, or modify client files. --server, --pg, and the AGENTSVIEW_MEMORY_SERVER, AGENTSVIEW_MEMORY_SERVER_TOKEN_FILE, and AGENTSVIEW_MEMORY_PG environment variables select the same read target used by agentsview mcp --profile memory.

agentsview memory session-start¶

Run the bounded conversation-memory lifecycle action used by native agent packages:

agentsview memory session-start
agentsview memory session-start --mode hosted-contributor [--target <pg-name>]
agentsview memory session-start --mode hosted-reader --server <url> \
  [--server-token-file <path>]
agentsview memory session-start --mode hosted-reader --pg [--target <pg-name>]
agentsview memory session-start --hook [--plugin-root <path>]

The default local mode ensures the writable local daemon is available, then asks it to run a coalesced background reconciliation. hosted-contributor notifies the already running PostgreSQL push watcher for the selected target; that owner keeps its existing debounce, credentials, embedding work, and push cadence. It does not start another writer. hosted-reader checks an explicit authenticated daemon or configured PostgreSQL read target without starting a local archive or claiming to refresh hosted data.

Every mode returns within 1.9 seconds and does not wait for archive-scale work. Set AGENTSVIEW_DISABLE_AUTO_SYNC=1 to skip only this automatic request; explicit sync commands and searches remain available. A contributor owner started by an older binary must be restarted once so it can advertise the lifecycle wake endpoint. The contributor wake is available on macOS and Linux; Windows contributors continue on the watcher's normal event and interval cadence.

Native packages can configure these flags with AGENTSVIEW_MEMORY_MODE, AGENTSVIEW_MEMORY_TARGET, AGENTSVIEW_MEMORY_SERVER, AGENTSVIEW_MEMORY_SERVER_TOKEN_FILE, and AGENTSVIEW_MEMORY_PG. Explicit target flags override the package environment as a group. --hook reports a failure to stderr and exits successfully so startup problems do not prevent the agent session from opening. --plugin-root also diagnoses standalone skill copies that would be loaded alongside the native package; it never changes those files.

agentsview friction¶

Build and read the Friction Log. Review must be enabled with [friction] enabled = true.

agentsview friction run [--date YYYY-MM-DD] [--rebuild] [--dry-run] [--format human|json | --json]
agentsview friction digest [--date D | --from D --to D] [--format md|json | --json]
agentsview friction findings [--date D] [--kind K] [--session ID] [--limit N] [--cursor C] [--format table|json | --json]
agentsview friction patterns [--kind K] [--since D] [--limit N] [--cursor C] [--format table|json | --json]
agentsview friction file <fingerprint> [--dry-run] [--format human|json | --json]
agentsview friction link <fingerprint> <issue>
agentsview friction unlink <fingerprint>

• friction run without flags builds every complete local day that has no digest yet. --date builds one day, --rebuild rebuilds an existing day while keeping the sessions it already covered, and --dry-run computes without writing. It prints one summary line per day, or the summary JSON with --json.
• friction digest prints the latest digest as Markdown unless --date or a range is given. --format json prints the stored summary JSON.
• friction findings lists stored findings. friction patterns ranks recurring patterns by occurrences and shows each pattern's Kata issue. --kind accepts correction, error, workaround, deferral, pattern, frustration, and interruption.
• friction file files a pattern to Kata, or links the issue Kata already holds for it. friction link and friction unlink set or remove a pattern's issue by hand. Only the AgentsView hub files.

Read commands use the running daemon (starting one when needed), an explicit --server <url>, or --pg for the configured PostgreSQL hub. Provide a --server token with AGENTSVIEW_SERVER_TOKEN or --server-token-file <path>. friction run, friction file, friction link, and friction unlink use the daemon when one is running and otherwise write the local archive directly.

agentsview mcp¶

Run a read-only Model Context Protocol server for assistant clients that can call MCP tools. The server exposes session search, listing, overview, message retrieval, content search, and usage-summary tools over the same service layer used by the CLI and HTTP API. See MCP Server for setup examples and operational guidance.

agentsview mcp
agentsview mcp --profile memory
agentsview mcp --http 127.0.0.1:8085
agentsview mcp --server http://127.0.0.1:8080
agentsview mcp status --json

agentsview mcp status --json lists local HTTP MCP listeners without starting one; stdio connections do not appear. See listener discovery for endpoint fields and token-file paths.

By default, agentsview mcp speaks stdio, which is the expected transport for local MCP clients such as Claude Desktop, Claude Code, and Codex. --http <addr> serves StreamableHTTP instead. Bare ports and :PORT values bind to 127.0.0.1; non-loopback binds require --http-allow-insecure plus a configured bearer token.

Local MCP mode reads through the AgentsView daemon, starts it when needed, and reuses the connection between tool calls. The MCP server does not open the local SQLite archive directly. See daemon-backed reads for when it finds the daemon again.

Use --profile memory when the client should discover only the get_memory_status, search_content, and get_messages conversation-memory tools. get_memory_status reports archive, lexical, semantic, vector coverage, and source-telemetry readiness without running a search probe. The default full profile preserves the complete MCP tool surface. Profile selection works with both stdio and StreamableHTTP and does not change backend selection.

Use --server <url> to point at an explicit running daemon. When the daemon requires auth, provide AGENTSVIEW_SERVER_TOKEN or --server-token-file <path>. Use --pg to read from configured PostgreSQL directly, or run agentsview replica pg serve and pass its URL with --server.

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.

agentsview skills¶

Install or list the bundled recall artifacts that teach coding-agent harnesses to consult AgentsView conversation history. Claude Code receives the agentsview-finding-history skill and the agentsview-search-conversations agent. Codex and other .agents/skills readers receive the skill with the same direct MCP workflow as its fallback. See Semantic Search for the workflow and upgrade guidance.

agentsview skills install [--harness claude|agents] [--project] [--force]
    [--server URL] [--server-token-file PATH]
agentsview skills list [--project] [--format json]
    [--server URL] [--server-token-file PATH]

install renders the package for each --harness (default both). Skills land under ~/.claude/skills/agentsview-finding-history/ and/or ~/.agents/skills/agentsview-finding-history/, with SKILL.md and a LICENSE sidecar in each directory. Claude's search agent lands at ~/.claude/agents/agentsview-search-conversations.md. That agent allowlists only mcp__agentsview__search_content and mcp__agentsview__get_messages, so the Claude MCP server entry must be named agentsview. --project uses the equivalent paths at the current git root. Each artifact has its own generated hash: install updates safe generated files, refuses hand-edited or foreign files unless --force is passed, continues processing the other artifacts, and exits non-zero if anything was refused. list reports HARNESS, ARTIFACT, LEVEL, STATE (missing, current, stale, modified, foreign), and PATH for every artifact.

--server / --server-token-file (or AGENTSVIEW_SKILLS_SERVER / AGENTSVIEW_SKILLS_SERVER_TOKEN_FILE) bake those flags into every example command so a remote-daemon install does not teach the local SQLite default. Values are shell-quoted, so a token path with a space stays one argument.

Precedence is explicit flags, then whatever the installed skill already bakes, then the environment. An installed skill therefore decides even when it bakes no remote, so exporting AGENTSVIEW_SKILLS_SERVER never marks an existing package stale in list; the variables only seed a package whose skill is not installed yet. The endpoint-neutral Claude agent never contains server flags. Pass --server "" to un-bake a remote and return the skill to local SQLite.

These variables are skills-only and named apart from AGENTSVIEW_SERVER_TOKEN on purpose: they do not change the CLI's default read path, and session search still needs --server unless the baked examples supply it.

agentsview completion¶

Generate a completion script for Bash, Fish, PowerShell, or Zsh. The command writes the script to standard output; it does not modify shell startup files. Pass --no-descriptions after the shell name to omit command descriptions.

Load completion for the current shell session:

source <(agentsview completion bash)

agentsview completion fish | source

agentsview completion powershell | Out-String | Invoke-Expression

source <(agentsview completion zsh)

For persistent completion, install the generated script in the location for the shell:

• Bash requires the bash-completion package. Write the script to /etc/bash_completion.d/agentsview on Linux or $(brew --prefix)/etc/bash_completion.d/agentsview on macOS.
• Fish loads ~/.config/fish/completions/agentsview.fish automatically.
• Zsh requires completion to be enabled with compinit. Write the script to ${fpath[1]}/_agentsview on Linux or $(brew --prefix)/share/zsh/site-functions/_agentsview on macOS.
• PowerShell users can add the current-session command above to their profile.

Run agentsview completion <shell> --help for the exact installation command and shell-specific prerequisites. Start a new shell after installing a generated script.

agentsview help¶

Print usage information.

agentsview help

Environment Variables¶

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