| title | CLI Reference |
|---|---|
| description | All AgentsView commands, flags, and environment variables |
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.jsoncapture 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.
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 raw-sync watch
agentsview raw-sync statusraw-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.
| Flag | Default | Description |
|---|---|---|
--server |
environment | Raw-sync server URL |
--device-id |
environment | Provisioned device ID |
--allow-insecure-http |
false |
Allow HTTP for a loopback server only |
--debounce |
2s |
Coalescing window for filesystem changes |
--interval |
15m |
Interval between bounded provider audits |
--audit-limit |
128 |
Maximum source work in each provider audit |
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. A deployment operator must provision the device ID and credential;
there is no public enrollment command yet. Accepted raw generations are not yet
parsed into hosted sessions. See Hosted Raw Sync for
the current boundary.
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.
agentsview daemon start
agentsview daemon status
agentsview daemon restart
agentsview daemon stop| Command | Behavior |
|---|---|
start |
Start the daemon, or report the existing writable daemon |
status |
Show writable daemon state, URL, PID, version, and uptime |
restart |
Stop and restart the writable daemon; start it if it is already stopped |
stop |
Stop the writable daemon, or report that it is already stopped |
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 pg serve and
agentsview 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.
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.
If a compatible server is already running, serve reports its URL and exits.
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.
agentsview serve [flags]As of 0.23.0, starting the server requires the explicit serve subcommand.
Running plain agentsview shows help instead of starting the web UI.
| Flag | Default | Description |
|---|---|---|
--host |
127.0.0.1 |
Host to bind to |
--port |
8080 |
Port to listen on |
--no-browser |
false |
Don't open browser on startup |
--no-sync |
false |
Disable initial, watched, and periodic sync |
--no-update-check |
false |
Disable automatic update checks |
--require-auth |
false |
Require a bearer token for API requests |
--background |
false |
Start agentsview serve as a managed background process |
--replace |
false |
Replace a running local daemon before starting |
--public-url |
Browser URL, also added to trusted origins | |
--public-origin |
Trusted browser origin (repeatable/comma-separated) | |
--proxy |
Managed proxy mode (caddy) |
|
--caddy-bin |
caddy |
Caddy binary path |
--proxy-bind-host |
127.0.0.1 |
Interface for managed proxy |
--public-port |
URL port or 8443 |
Managed Caddy HTTP/HTTPS listener and URL port |
--tls-cert |
TLS certificate path | |
--tls-key |
TLS key path | |
--allowed-subnet |
Client CIDR allowlist (repeatable/comma-separated) |
The server auto-discovers an available port if 8080 is busy. See
Remote Access for details on the remote access and proxy
flags.
Examples:
agentsview serve # defaults
agentsview serve --port 9090 # custom port
agentsview serve --no-browser # disable browser auto-open
agentsview serve --background # start managed background server
agentsview serve --replace # replace an existing daemon
agentsview serve --public-url https://agents.example.comOn startup, the server:
- Loads or creates
~/.agentsview/sessions.db - Runs initial sync across all discovered session directories
- Starts the file watcher (500ms event batching; watcher sync starts remain at least five seconds apart)
- Starts periodic sync (every 15 minutes)
- Serves the Svelte SPA and REST API
The server shuts down cleanly on Ctrl+C, flushing the database and stopping
file watchers.
The existing serve background and lifecycle forms remain available:
agentsview serve --background
agentsview serve status
agentsview serve restart
agentsview serve stopThe 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. 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.
When a writable daemon is already running, a newer release binary automatically
replaces an older compatible daemon before starting. Development builds,
downgrades, and forward API/data-version conflicts do not auto-replace; use
--replace when you deliberately want this invocation to stop the running
daemon first. If the SQLite archive itself has a newer data version than the
current binary can open, serve refuses before stopping the old daemon.
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. A background 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.
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, and duckdb push. If a writable daemon is known to
own the archive but is not reachable, these commands refuse instead of writing
directly.
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 and asks you to stop the daemon, wait for idle shutdown, or
retry after the offline operation finishes.
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 syncThe 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 sync [flags]| Flag | Default | Description |
|---|---|---|
--full |
false |
Force a full resync regardless of data version |
--target |
Exchange normalized artifacts with a trusted folder | |
--host |
SSH hostname for deprecated remote sync | |
--user |
SSH username for deprecated remote sync | |
--port |
22 |
SSH port for deprecated remote sync |
Examples:
agentsview sync # incremental sync and exit
agentsview sync --full # full resync and exit
agentsview sync --target /path/to/shared-folder
agentsview sync --host buildbox.local
agentsview sync --host buildbox.local --user wes --port 2222After 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 that remote host and fails fast on
error. If the local daemon has a matching configured [[remote_hosts]] entry,
the daemon uses that stored entry and its configured transport. Otherwise,
--host performs an ad hoc SSH sync: it resolves the supported agent session
directories on the remote machine, transfers the source session data locally,
and indexes it into your local archive. SSH remote sync is deprecated and
receives only critical fixes; use configured HTTP remote sync for new setups.
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 sync normally. This is not SSH remote sync: 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.
As of 0.33.0, remote hosts can also be declared in ~/.agentsview/config.toml
so a single bare agentsview sync covers a whole fleet:
[[remote_hosts]]
host = "buildbox.local"
transport = "ssh" # optional; default
user = "wes" # optional
port = 2222 # optional, defaults to 22
[[remote_hosts]]
host = "devbox1"
transport = "http"
url = "http://devbox1.tailnet.ts.net:8080"
token = "remote-token"With hosts configured, agentsview sync (no --host) includes local sources
and configured HTTP hosts in one coordinated sync. During a full or automatic
data-version rebuild, AgentsView prepares every HTTP mirror, bulk-ingests the
local and HTTP sources into one temporary database with FTS updates suspended,
rebuilds FTS once, and atomically swaps the completed archive into place. SSH
hosts run through their existing active-archive path only after that swap.
--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, unreachable, or times out is skipped; reachable HTTP hosts still join
the combined rebuild. Other HTTP preparation or contributor failures abort the
combined rebuild without replacing the active archive or running SSH. Ordinary
incremental and post-swap SSH failures retain per-host reporting, and the
command exits non-zero for any failure other than an unavailable configured HTTP
host. See Incremental Sync.
agentsview sync --host X syncs one host, not the whole configured list. When
the local daemon knows a configured host with that identity, it uses the stored
entry and transport so HTTP hosts can be selected by host name. Without a
matching configured host, --host remains an ad hoc SSH sync. SSH remote sync
is deprecated and receives only critical fixes. It remains non-interactive in
both forms — it requires key-based passwordless SSH and never prompts for a
password. Prefer configured HTTP remote 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. The per-host token is required and must match 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.
Delete sessions matching one or more filters. At least one filter is required.
agentsview prune [flags]| Flag | Default | Description |
|---|---|---|
--project |
Sessions whose project contains this substring | |
--max-messages |
-1 |
Sessions with at most N messages |
--before |
Sessions that ended before this date (YYYY-MM-DD) |
|
--first-message |
Sessions whose first message starts with this text | |
--dry-run |
false |
Show what would be pruned without deleting |
--yes |
false |
Skip confirmation prompt |
Examples:
# Preview what would be deleted
agentsview prune --project "scratch" --dry-run
# Delete short sessions from before 2025
agentsview prune --max-messages 2 --before 2025-01-01
# Delete sessions starting with a specific message
agentsview prune --first-message "test" --yes
# Combine filters (AND logic)
agentsview prune --project "old-project" --max-messages 5 --before 2025-06-01The prune command displays the number of sessions deleted and disk space
reclaimed. Use --dry-run first to verify the filter matches what you expect.
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 startUse --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.
Rebuild the local SQLite archive into a staged, verified database and reclaim free pages. The command also truncates the WAL. It does not compress or deduplicate live tool-result payloads, so it does not change future growth from those payloads.
agentsview db compact [flags]| Flag | Default | Description |
|---|---|---|
--staging-dir |
Filesystem location for the staged database | |
--dry-run |
false |
Report the estimate without changing the archive |
--keep-backup |
false |
Keep the original database backup |
--yes |
false |
Skip the confirmation prompt |
--format |
human |
Use json for machine-readable output |
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 db compact \
--staging-dir /mnt/cache/data-cache/agentsview-compact \
--keep-backup --yesWhen 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.
Remove supported inline image payloads from stored tool-result rows. The
command requires --images; it uses the existing direct maintenance write
owner and confirmation prompt. 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.
agentsview db strip --images [flags]| Flag | Default | Description |
|---|---|---|
--images |
false |
Required image cleanup operation |
--project |
Sessions whose project contains this substring | |
--before |
Sessions that ended before this date (YYYY-MM-DD) |
|
--dry-run |
false |
Preview selected sessions and byte counts |
--yes |
false |
Skip confirmation |
--format |
human |
Use json for machine-readable output |
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.
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 when a tool result's output is switched to formatted mode and
every other block in that result is a text block. 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 changes currently stored rows. A later keep-mode reparse or full
resync can restore inline bytes from provider source files. The
tool_result_images = "drop" policy keeps supported images projected during
future ingestion and full resync. The 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.
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.
agentsview db migrate --images [flags]| Flag | Default | Description |
|---|---|---|
--images |
false |
Required image migration operation |
--project |
Sessions whose project contains this substring | |
--before |
Sessions that ended before this date (YYYY-MM-DD) |
|
--dry-run |
false |
Preview selected sessions and byte counts |
--yes |
false |
Skip confirmation |
--format |
human |
Use json for machine-readable output |
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.
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 jsonagentsview 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:
| Field | Type | Meaning |
|---|---|---|
schema_version |
integer | Version of this JSON contract; currently 1 |
name |
string | Canonical tool name, always agentsview |
version |
string | Build version |
commit |
string | Source commit recorded at build time |
build_date |
string | UTC build timestamp, or an empty string |
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.
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 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. session usage, token-use, and usage statusline still wait for
initial sync, including when they reuse a daemon started by daily usage.
Statusline limits the complete wait and report request to 30 seconds.
agentsview usage daily [flags]| Flag | Default | Description |
|---|---|---|
--format |
human |
Output format: human or json |
--json |
false |
Alias for --format json |
--since |
30 days ago |
Start of window, a duration like 28d or a YYYY-MM-DD date, inclusive |
--until |
End of window, a duration like 28d or a YYYY-MM-DD date, inclusive |
|
--all |
false |
Scan all history; overrides the default 30-day window |
--agent |
Filter by agent name | |
--breakdown |
false |
Show per-model rows and populate detailed JSON breakdown arrays |
--offline |
false |
Read the archive directly without sync or pricing fetches |
--no-sync |
false |
Skip source refresh; a new daemon starts without automatic sync |
--timezone |
system | IANA timezone name for date bucketing |
Examples:
agentsview usage daily # last 30 days
agentsview usage daily --all # full history
agentsview usage daily --since 14d # last 14 days
agentsview usage daily --since 2026-04-01 --breakdown
agentsview usage daily --json --agent claudePrint today's total estimated cost as a single line, for shell prompts and tmux status lines.
agentsview usage statusline [flags]| Flag | Default | Description |
|---|---|---|
--format |
human |
Output format: human or json |
--json |
false |
Alias for --format json |
--agent |
Filter by agent name | |
--offline |
false |
Read the archive without sync or pricing fetches |
--no-sync |
false |
Skip source refresh |
Example:
$ agentsview usage statusline
$9.61 today$ agentsview usage statusline --json
{
"date": "2026-08-04",
"cost": {
"microdollars": 9610000
}
}See Token Usage & Costs for integration examples (Starship, tmux).
Fetch Cursor Admin API usage events and store them in the local archive so they contribute to the Usage dashboard and daily reports.
agentsview usage cursor [flags]| Flag | Default | Description |
|---|---|---|
--since |
30 days ago |
Start date (YYYY-MM-DD), inclusive |
--until |
today | End date (YYYY-MM-DD), inclusive |
--all |
false |
Include all history |
--page-size |
100 |
Events requested per Cursor API page |
--email |
config | Filter by Cursor team member email |
--user-id |
config | Filter by Cursor team member user ID |
Examples:
agentsview usage cursor
agentsview usage cursor --since 2026-05-01 --until 2026-05-31
agentsview usage cursor --all --email [email protected]See Cursor Admin Usage Events for setup and reporting behavior.
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 activity report [flags]| Flag | Default | Description |
|---|---|---|
--preset |
Range preset: day, week, month, or custom |
|
--date |
today | Anchor date for day/week/month presets (YYYY-MM-DD) |
--from |
Start instant for custom range (RFC3339) | |
--to |
End instant for custom range (RFC3339) | |
--timezone |
system | IANA timezone for range bucketing |
--bucket |
automatic | Bucket size: 5m, 15m, 1h, 1d, or 1w |
--project |
Filter by project | |
--agent |
Filter by agent name | |
--machine |
Filter by machine name | |
--format |
human |
Output format: human or json |
--json |
false |
Alias for --format json |
--no-sync |
false |
Skip on-demand sync before querying |
--offline |
false |
Use fallback pricing only |
Examples:
agentsview activity report --preset day --date 2026-06-20
agentsview activity report --preset week --date 2026-06-20 --json
agentsview activity report --preset custom \
--from 2026-06-20T14:00:00Z \
--to 2026-06-20T18:00:00Z \
--bucket 15mThe 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.
!!! note "Deprecated"
As of 0.30.0, `agentsview token-use` is a deprecated alias for
[`agentsview session usage`](/docs/session-api/#agentsview-session-usage). Both
commands accept the same `<session-id>` argument. `token-use` always emits the
same JSON shape that `session usage --format json` emits (now extended with a
cost estimate). New scripts should use `agentsview session usage`.
Print machine-readable token usage data and a cost estimate for a single session.
agentsview token-use <session-id>Session ID format depends on the agent. For example, Claude root sessions
usually use UUIDs like 550e8400-e29b-41d4-a716-446655440000, Claude subagents
use IDs like agent-a86574e, and some other agents use prefixes such as
codex:my-session-id. Raw session IDs emitted by the underlying agent are also
accepted when AgentsView can resolve them back to the canonical stored session.
If the AgentsView server is already running, the command reads the current database state. If no server is running, it performs an on-demand sync for the requested session first.
As of 0.40.0, the reported totals include every subagent transcript the session
spawned, so the cost matches what the session actually spent. 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.
Sync sessions from local SQLite to PostgreSQL. See PostgreSQL Sync for full documentation.
agentsview pg push [target] [flags]| Flag | Default | Description |
|---|---|---|
--full |
false |
Force full local resync and re-push |
--no-vectors |
false |
Skip the semantic-search vector phase for this run |
--projects |
Comma-separated projects to push (inclusive) | |
--exclude-projects |
Comma-separated projects to exclude from push | |
--all-projects |
false |
Ignore configured project filters for this run |
--all |
false |
Push every configured PostgreSQL target sequentially |
--watch |
false |
Run continuously, pushing on change plus a periodic floor |
--debounce |
30s |
Coalesce window after a change before pushing (--watch only) |
--interval |
15m |
Periodic floor push interval (--watch only) |
See PostgreSQL Sync — Project Filtering for details on how filtering interacts with the push watermark.
Show PostgreSQL sync status.
agentsview pg status [target] [flags]| Flag | Default | Description |
|---|---|---|
--all |
false |
Show status for every configured PostgreSQL target |
--projects |
Comma-separated projects whose push status to show | |
--exclude-projects |
Comma-separated excluded projects whose push status to show | |
--all-projects |
false |
Ignore configured project filters for this status |
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 pg serve [flags]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.
Install and manage the PostgreSQL auto-push service, which runs
agentsview pg push --watch in the background. Supported service managers are
launchd on macOS and systemd --user on Linux. See
PostgreSQL Sync — agentsview pg service
for setup notes.
agentsview pg service install
agentsview pg service status
agentsview pg service logs [-f]
agentsview pg service start
agentsview pg service stop
agentsview pg service uninstall| Command | Description |
|---|---|
install |
Generate the service unit, enable it, and start it |
status |
Show the service-manager status plus last successful push |
logs -f |
Follow pg-watch.log under the AgentsView data directory |
start |
Start the installed service |
stop |
Stop the installed service |
uninstall |
Stop and remove the service unit |
Inspect and drop semantic-search embedding generations stored in PostgreSQL. See Semantic Search — Maintenance for details.
agentsview pg vectors list [flags]
agentsview pg vectors drop <id> [flags]| Command | Description |
|---|---|
list |
List generations with model, dimension, document/chunk counts, and contributing machines |
drop <id> |
Drop a generation and all of its embeddings (prompts for confirmation) |
| Flag | Default | Description |
|---|---|---|
--target |
PG target name (default: the default configured target) | |
--yes |
false |
Skip the confirmation prompt (drop only) |
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 duckdb push # mirror SQLite into sessions.duckdb
agentsview duckdb status # show mirror sync status
agentsview duckdb serve # read-only web UI from the mirror
agentsview duckdb quack serve # expose the mirror over Quackduckdb 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.
List all projects in the local database with their session counts.
agentsview projects [flags]| Flag | Default | Description |
|---|---|---|
--format |
human |
Output format: human or json |
--json |
false |
Alias for --format json |
Examples:
agentsview projects # tabular output
agentsview projects --json # JSON arrayInspect session intelligence in a human-friendly CLI view. See Session Intelligence for the scoring and signal model.
agentsview health [session-id] [flags]| Flag | Default | Description |
|---|---|---|
--format |
human |
Output format: human or json |
--json |
false |
Alias for --format json |
--limit |
20 |
Number of sessions to list when no session ID is given |
Examples:
agentsview health
agentsview health --limit 50
agentsview health 550e8400-e29b-41d4-a716-446655440000
agentsview health agent-a86574e --jsonWithout 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.
Experimental window-scoped workspace analytics across sessions and git activity. See Stats for the full write-up.
agentsview stats [flags]| Flag | Default | Description |
|---|---|---|
--format |
human |
Output format: human or json |
--json |
false |
Alias for --format json |
--since |
28d |
Start of window, either YYYY-MM-DD or a compact duration like 28d |
--until |
End of window as YYYY-MM-DD |
|
--agent |
all |
Restrict to one agent or use all |
--include-project |
Repeatable project allowlist | |
--exclude-project |
Repeatable project blocklist | |
--timezone |
local | Timezone used for temporal reporting |
Examples:
agentsview stats
agentsview stats --format json --since 2026-04-01 --until 2026-04-15
agentsview stats --agent claude --include-project agentsviewThe 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.
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.
agentsview doctor syncThe report includes:
- data directory and SQLite database path
- whether the database exists and is readable
- SQLite
user_versionand 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
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 parse-diff [flags]| Flag | Default | Description |
|---|---|---|
--agent |
Restrict to one agent; repeatable | |
--limit |
0 |
Maximum number of source files to inspect, newest first (0 means all) |
--fail-on-change |
false |
Exit non-zero when changes or parse errors are found |
--format |
human |
Output format: human or json |
--json |
false |
Alias for --format json |
--verbose / -v |
false |
Include more detail in the human report |
Examples:
agentsview parse-diff --agent claude --limit 100
agentsview parse-diff --agent codex --fail-on-change
agentsview parse-diff --json > parser-report.jsonparse-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:
racedmeans the source changed whileparse-diffwas running. It is reported for review but does not fail--fail-on-change.incremental_skewmeans 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_resyncmeans the stored data version is behind the running binary; the next data-version resync rewrites those rows.
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.
Import Claude.ai, ChatGPT, or Gemini Apps conversations into the local database. See Chat Import for full documentation.
agentsview import --type <type> <path>| Flag | Default | Description |
|---|---|---|
--type |
Import type: claude-ai, chatgpt, or gemini-apps (required) |
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 import --type claude-ai ~/Downloads/claude.zip
agentsview import --type chatgpt ~/Downloads/chatgpt.zip
agentsview import --type claude-ai ./conversations.json
agentsview import --type gemini-apps ~/Downloads/takeout.zipExport 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]| Flag | Default | Description |
|---|---|---|
--format |
json |
Output format: json or ndjson |
--limit |
500 |
Maximum sessions to return; max db.MaxSessionLimit |
--cursor |
Opaque cursor from a previous response | |
--all |
false |
Export every eligible page as one output stream |
--project |
Filter by exact project name | |
--exclude-project |
Exclude sessions from the given project | |
--machine |
Filter by machine name | |
--git-branch |
Filter by project/branch token | |
--agent |
Filter by agent name | |
--date |
Include sessions active on YYYY-MM-DD |
|
--date-from |
Include sessions active on or after YYYY-MM-DD |
|
--date-to |
Include sessions active on or before YYYY-MM-DD |
|
--active-since |
Include sessions active since an RFC3339 timestamp | |
--min-messages |
0 |
Minimum total message count |
--max-messages |
0 |
Maximum total message count |
--min-user-messages |
0 |
Minimum user message count |
--include-one-shot |
false |
Include one-shot sessions, which are excluded by default |
--include-automated |
false |
Include automated sessions, which are excluded by default |
--include-children |
false |
Include subagent/child sessions |
--outcome |
Comma-separated outcome filter | |
--health-grade |
Comma-separated health grade filter | |
--min-tool-failures |
Minimum tool-failure signal count | |
--has-secret |
false |
Only sessions with detected secret leaks |
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 agentsviewThe 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.
When --cursor is present, only --format, --json, and --limit 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":"..."}Export canonical UTC-hour activity and usage documents, coherent UTC-day snapshots, or compact date-range digests from the local archive. See Reporting Export for the v3 wire schema, quiet-hour semantics, snapshot guarantee, and digest rules.
agentsview export hour 2026-07-28-13
agentsview export day 2026-07-28
agentsview export digest --from 2026-06-28 --to 2026-07-27Hour 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 are inclusive and limited to 31 dates. Integrations should
validate the emitted schema_version: 3 and content digest before accepting a
document. Version 3 is the default and the only accepted --schema-version;
versions 1 and 2 are no longer emitted. Update consumers and refresh stored
digests when upgrading.
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 tool-calls <id> # flat tool-call list
agentsview session export <id> # stream raw source file
agentsview session sync <path-or-id> # parse + insert
agentsview session watch <id> # NDJSON event stream
agentsview session search <pattern> # content search across sessions
agentsview session usage <id> # token usage and cost estimate
agentsview session usage <id> --own-only # exclude subagent transcriptssession usage attributes each subagent transcript's spend to the session that
spawned it, so a parent that delegated most of its work still reports the full
cost. --own-only restores the older own-session output.
session search supports substring (default), --regex, --fts, --semantic,
and --hybrid modes. Repeatable --exclude-session <id> drops matches from
those sessions before --limit. 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. 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 and automated sessions by default.
When that hides matching sessions on the first page, it reports the counts and
the corresponding --include-one-shot or --include-automated flags on stderr.
Stdout, including --format json, keeps its existing shape for pipelines.
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 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.
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 embeddings build # build or refresh the index
agentsview embeddings list # list embedding generations
agentsview embeddings activate <id> # activate a generation
agentsview embeddings retire <id> # retire a generationInspect 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-runModel-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.
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 --http 127.0.0.1:8085
agentsview mcp --server http://127.0.0.1:8080By 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 is daemon-backed. Each tool call resolves the local AgentsView daemon and starts it when needed, so a long-lived MCP server can keep working after the daemon exits due to idleness. The MCP server does not fall back to opening the local SQLite archive directly.
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 pg serve and
pass its URL with --server.
| Flag | Default | Description |
|---|---|---|
--http <addr> |
Serve StreamableHTTP instead of stdio | |
--http-allow-insecure |
false |
Allow non-loopback HTTP binds; requires bearer auth |
--server <url> |
Explicit daemon URL for MCP tool calls | |
--server-token-file <path> |
Bearer token file for an explicit daemon URL | |
--pg |
false |
Read from configured PostgreSQL |
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 findingssecrets scan walks the archive, applies the full ruleset (definite + candidate
tiers), and writes new findings to the secret_findings table. Pass
--backfill to scan only sessions that haven't yet been scanned at the current
ruleset version — the inline scan that runs during sync only stamps
definite-tier findings, so --backfill is how you pick up the heuristic
candidates without re-scanning the whole archive.
secrets list returns redacted findings by default. Pass --reveal to print
the raw values — this only works against a localhost-bound daemon and emits a
warning to stderr.
| Flag | Used by | Description |
|---|---|---|
--format |
both | human or json (inherited from secrets) |
--json |
both | Alias for --format json (inherited from secrets) |
--backfill |
scan | Scan only sessions not yet scanned at the current ruleset version |
--project |
both | Limit to a project |
--agent |
both | Limit to an agent |
--date-from |
both | Sessions on or after YYYY-MM-DD |
--date-to |
both | Sessions on or before YYYY-MM-DD |
--rule |
list | Filter by rule name (e.g. aws-access-key) |
--confidence |
list | definite, candidate, or all (default definite) |
--reveal |
list | Show unredacted values (localhost-only) |
--limit |
list | Max findings (default 50, max 500) |
--cursor |
list | Pagination cursor from a previous response |
Install or list the bundled skill files that teach coding-agent harnesses
(Claude Code, Codex, and other .agents/skills readers) to search AgentsView
history. See Semantic Search
for what the skill does and when to re-run it.
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 embedded agentsview-finding-history skill for each
--harness (default both) and writes SKILL.md under
~/.claude/skills/agentsview-finding-history/ and/or
~/.agents/skills/agentsview-finding-history/, or under .claude/skills/ /
.agents/skills/ at the current git root with --project. It overwrites an
unmodified generated file, refuses a hand-edited or foreign file unless
--force is passed, and exits non-zero on any refusal. list reports HARNESS,
LEVEL, STATE (missing, current, stale, modified, foreign), and PATH
for every harness.
--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 file already bakes,
then the environment. An installed file therefore decides even when it bakes
no remote, so exporting AGENTSVIEW_SKILLS_SERVER never marks existing skills
stale in list; the variables only seed a file that is not installed yet. Pass
--server "" to un-bake a remote and go back to a local-SQLite skill.
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.
Print usage information.
agentsview help| Variable | Default | Description |
|---|---|---|
AIDER_DIR |
unset | Aider discovery root; set this to opt into scanning a code root |
AMP_DIR |
~/.local/share/amp/threads |
Deprecated; historical local Amp thread JSON files only |
ANTIGRAVITY_DIR |
~/.gemini/antigravity |
Google Antigravity IDE sessions directory |
ANTIGRAVITY_CLI_DIR |
~/.gemini/antigravity-cli |
Google Antigravity CLI sessions directory |
ANTIGRAVITY_KEY |
Optional key for decrypting Antigravity CLI .pb transcripts (defaults to summary mode without it) |
|
CLAUDE_PROJECTS_DIR |
~/.claude/projects |
Claude Code projects directory |
CLAUDE_CONFIG_DIR |
unset | Claude Code config home that re-roots the default projects/ discovery path |
OPENCLAUDE_PROJECTS_DIR |
~/.openclaude/projects |
OpenClaude projects directory |
OPENCLAUDE_CONFIG_DIR |
unset | OpenClaude config home that re-roots the default projects/ discovery path |
COWORK_DIR |
(platform-specific) | Claude Desktop cowork sessions directory |
CODEX_SESSIONS_DIR |
~/.codex/sessions |
Codex sessions directory |
CODEX_HOME |
unset | Codex home that re-roots the default sessions/ and archived_sessions/ discovery paths |
COMMANDCODE_PROJECTS_DIR |
~/.commandcode/projects |
Command Code projects directory |
COPILOT_DIR |
~/.copilot |
Copilot CLI sessions directory |
CORTEX_DIR |
~/.snowflake/cortex/conversations |
Cortex Code conversations directory |
CURSOR_PROJECTS_DIR |
~/.cursor/projects |
Cursor transcripts directory |
DEEPSEEK_TUI_SESSIONS_DIR |
~/.codewhale/sessions and ~/.deepseek/sessions |
DeepSeek TUI sessions directory |
DEEPSEEK_HARNESS_SESSIONS_DIR |
~/.dsh/sessions |
DeepSeek Harness sessions directory |
DSH_HOME |
unset | DeepSeek Harness home that re-roots the default sessions/ discovery path |
FORGE_DIR |
~/.forge |
Forge directory (contains .forge.db) |
GEMINI_DIR |
~/.gemini |
Gemini CLI directory |
GOOSE_PATH_ROOT |
(platform-specific) | Goose path root; sessions are read from <root>/data/sessions/sessions.db |
GPTME_DIR |
~/.local/share/gptme/logs |
gptme logs directory |
GROK_DIR |
~/.grok/sessions |
Grok sessions directory |
HERMES_SESSIONS_DIR |
~/.hermes/sessions |
Hermes Agent sessions directory |
IFLOW_DIR |
~/.iflow/projects |
iFlow projects directory |
KILO_DIR |
~/.local/share/kilo |
Kilo data directory |
KILO_LEGACY_DIR |
(platform-specific) | Kilo legacy VS Code extension data directory |
KIMI_DIR |
~/.kimi/sessions and ~/.kimi-code/sessions |
Kimi sessions directory |
KIMI_WORK_DIR |
(platform-specific) | Kimi Work (kimi-desktop daimon) sessions directory |
KIRO_SESSIONS_DIR |
~/.kiro/sessions/cli and ~/.local/share/kiro-cli |
Kiro CLI sessions directory (JSONL and SQLite) |
KIRO_IDE_DIR |
(platform-specific) | Kiro IDE sessions directory |
MIMOCODE_DIR |
~/.local/share/mimocode |
MiMoCode data directory |
VIBE_SESSIONS_DIR |
~/.vibe/logs/session |
Mistral Vibe sessions directory |
OMP_DIR |
~/.omp/agent/sessions |
OhMyPi sessions directory |
OPENCLAW_DIR |
~/.openclaw/agents and ~/.kimi_openclaw/agents |
OpenClaw agents directory |
OPENCODE_DIR |
~/.local/share/opencode |
OpenCode data directory |
OPENCODEREVIEW_DIR |
~/.opencodereview/sessions |
Open Code Review sessions directory |
OPENHANDS_CONVERSATIONS_DIR |
~/.openhands/conversations |
OpenHands CLI conversations directory |
PI_DIR |
~/.pi/agent/sessions |
Pi sessions directory |
PI_CODING_AGENT_DIR |
unset | Pi agent home that re-roots the default sessions/ discovery path |
PI_CODING_AGENT_SESSION_DIR |
unset | Pi session directory override; PI_DIR takes precedence |
PRIME_AGENT_SESSION_DIR |
~/.prime/agent/sessions |
Prime Agent sessions directory |
PIEBALD_DIR |
~/.local/share/piebald |
Piebald directory (contains app.db) |
POOLSIDE_DIR |
(platform-specific) | Poolside Agent CLI trajectory directory |
POSIT_ASSISTANT_DIR |
~/.posit/assistant/workspaces |
Posit Assistant workspaces directory |
POSITRON_DIR |
(platform-specific) | Positron Assistant user directory |
QCLAW_DIR |
~/.qclaw/agents |
QClaw agents directory |
QODER_PROJECTS_DIR |
Legacy and platform-specific roots | Qoder projects directory; see Session Discovery |
QWEN_PROJECTS_DIR |
~/.qwen/projects |
Qwen Code projects directory |
QWENPAW_DIR |
~/.copaw/workspaces |
QwenPaw workspaces directory |
REASONIX_DIR |
~/.reasonix and ~/AppData/Roaming/reasonix |
Reasonix data directory |
ROOCODE_DIR |
(platform-specific) | RooCode VS Code extension data directory |
SHELLEY_DIR |
~/.config/shelley |
Shelley data directory |
TRAE_DIR |
(platform-specific) | Trae editor user-data directory |
VISUALSTUDIO_COPILOT_DIR |
(platform-specific) | Visual Studio Copilot traces directory |
VSCODE_COPILOT_DIR |
(platform-specific) | VS Code Copilot sessions directory |
WINDSURF_DIR |
(platform-specific) | Windsurf user-data directory |
WARP_DIR |
(platform-specific) | Warp database directory |
WORKBUDDY_PROJECTS_DIR |
~/.workbuddy/projects |
WorkBuddy projects directory |
ZCODE_DIR |
~/.zcode/cli/db and ~/.zcode/cli |
ZCode data directory (contains db.sqlite) |
ZED_DIR |
(platform-specific) | Zed data directory (contains threads/threads.db) |
ZENCODER_DIR |
~/.zencoder/sessions |
Zencoder sessions directory |
AGENTSVIEW_DATA_DIR |
~/.agentsview |
Data directory (database, config) |
AGENTSVIEW_AUTH_TOKEN |
Bearer token for require_auth; overrides auth_token in config.toml |
|
AGENTSVIEW_SKILLS_SERVER |
Remote daemon URL baked into skills install examples; not a default for session commands |
|
AGENTSVIEW_SKILLS_SERVER_TOKEN_FILE |
Token file path baked into skills install examples with AGENTSVIEW_SKILLS_SERVER |
|
AGENTSVIEW_PG_URL |
PostgreSQL connection URL | |
AGENTSVIEW_PG_MACHINE |
Machine name for PG push sync | |
AGENTSVIEW_PG_SCHEMA |
agentsview |
PostgreSQL schema name |
AGENTSVIEW_DUCKDB_PATH |
~/.agentsview/sessions.duckdb |
DuckDB mirror file path |
AGENTSVIEW_DUCKDB_URL |
Remote Quack endpoint URL for duckdb status and duckdb serve (read side only) |
|
AGENTSVIEW_DUCKDB_TOKEN |
Quack authentication token | |
AGENTSVIEW_DUCKDB_MACHINE |
Machine name for DuckDB push | |
AGENTSVIEW_GITHUB_TOKEN |
GitHub token used for local Gist publishing fallback and agentsview stats PR aggregation |
|
AGENTSVIEW_DISABLE_UPDATE_CHECK |
Set to 1 to disable the update check |
|
AGENTSVIEW_ARCHIVE_CONTENT |
full |
Archive storage policy when config.toml sets none: full, transcripts, or usage |
AGENTSVIEW_NO_DAEMON |
Set to 1, true, yes, or on to disable CLI daemon auto-start |
|
AGENTSVIEW_DAEMON_IDLE_TIMEOUT |
20m |
Override idle self-shutdown duration for detached background daemons |
AGENTSVIEW_TELEMETRY_ENABLED |
Set to 0 to disable anonymous daemon telemetry |
Environment variables override the built-in defaults. Set them in your shell profile or pass them inline:
AGENTSVIEW_DATA_DIR=/tmp/av-test agentsview serveSet tool_result_images = "offload" to offload supported tool-result images on future ingestion. Run agentsview db migrate --images to retry retained inline images after an asset-write failure. The raw agentsview session export command continues to stream provider source bytes. See image storage for backup and remote-backend limits.