← Back to README

CLI Reference

This reference is generated from the live polylogue --help surface inside the project devshell.

Top-Level Command

Usage: polylogue [OPTIONS] [COMMAND] [ARGS]...

  Polylogue - AI session archive.

  Dispatch model (query-first):
      Use `polylogue find QUERY then ACTION` for query-result workflows.
      Quoted query text is also accepted when followed by an action:
      `polylogue 'QUERY' then read`.
      Run `polylogue --help` to see the full subcommand list, or
      `polylogue --diagnose <args>` to have the parser explain how it
      routed your invocation.

  Product roles:
      Search/read/action:   find QUERY then read|select|mark|analyze|delete|continue; facets
      Setup/demo/evidence:  config, init, import, demo, tutorial
      Reader/TUI:           dashboard --status, dashboard
      Operations:           status (same as polylogue ops status), ops diagnostics, ops maintenance, ops backup

  Query mode (default):
      polylogue find "search terms"
      polylogue --origin claude-ai-export --since "last week" find "search terms"
      polylogue --latest find 'repo:polylogue' then read --to browser

  Verbs (actions on matched sessions):
      polylogue find id:abc then read          # exact ref: one selected session
      polylogue find id:abc then select --json # expose selected-session identity
      polylogue find id:abc then read --view messages
      polylogue find id:abc then read --to browser
      polylogue find id:abc then analyze --facets
      polylogue facets --query "vector store" --format json
      polylogue find "urgent" then delete --dry-run
      polylogue find 'repo:polylogue' then read --all --format ndjson

  Combined filters:
      polylogue --referenced-path README.md find 'repo:polylogue' then read
      polylogue find 'actions where tool:bash AND text:pytest' then read --view messages
      polylogue --action-sequence file_read,file_edit,shell find 'repo:polylogue' then analyze
      polylogue --action-text "pytest -q" find 'repo:polylogue' then read
      polylogue find 'pytest -q tests/unit/core/test_semantic_facts.py' --retrieval-lane actions
      polylogue --origin claude-code-session --since 2026-01-01 find 'repo:polylogue' then analyze --by repo --format json
      polylogue find 'actions where action:file_edit AND path:polylogue/cli' then read --view messages
      polylogue find 'near:"sqlite locking bug in parser"' then read

  Modifiers (write operations):
      polylogue find "urgent" then mark --tag-add review

  See also:
      polylogue --help                  # this screen
      polylogue find --help             # query workflow help
      polylogue <subcommand> --help     # per-subcommand help
      polylogue --diagnose <args>       # explain parser decisions

Options:
  --help-markdown                 Emit the full --help tree (root + every
                                  subcommand) as Markdown and exit.
  -i, --id TEXT                   Session ID (exact or prefix match)
  -c, --contains TEXT             FTS term (repeatable = AND)
  --exclude-text TEXT             Exclude FTS term
  --retrieval-lane LANE           Query lane: dialogue FTS, action text, or
                                  hybrid
  --lexical                       Force FTS-only search.
  --semantic                      Treat the query as a similarity prompt
                                  (vector-only; requires embeddings).
  --origin TEXT                   Include origins (comma = OR)
  --exclude-origin TEXT           Exclude origins
  -r, --repo TEXT                 Filter by repository name (comma = OR)
  --project TEXT                  Filter by provider project ref, e.g. ChatGPT
                                  g-p-<id> (comma = OR)
  -t, --tag TEXT                  Include tags (comma = OR, supports
                                  key:value)
  --exclude-tag TEXT              Exclude tags
  --title TEXT                    Title contains
  --referenced-path TEXT          Referenced file path contains substring
                                  (repeatable = AND)
  --cwd-prefix TEXT               Filter sessions whose recorded working
                                  directory starts with this prefix
  --action ACTION                 Require semantic action category (repeatable
                                  = AND)
  --exclude-action ACTION         Exclude semantic action category (repeatable
                                  = AND)
  --action-sequence TEXT          Require ordered semantic action subsequence
                                  (comma-separated)
  --action-text TEXT              Require text within normalized action
                                  evidence (repeatable = AND)
  --tool TEXT                     Require normalized tool name (repeatable =
                                  AND)
  --exclude-tool TEXT             Exclude normalized tool name (repeatable =
                                  AND)
  --similar TEXT                  Semantic similarity query (requires
                                  embeddings)
  --has TEXT                      Filter by content: thinking (reasoning),
                                  tools (calls), summary, attachments
  --has-tool-use                  Only sessions with tool use (SQL pushdown)
  --has-thinking                  Only sessions with thinking blocks (SQL
                                  pushdown)
  --has-paste                     Only sessions with paste evidence (SQL
                                  pushdown)
  --typed-only                    Only sessions without paste evidence (typed
                                  prose only)
  --min-messages INTEGER          Minimum message count
  --max-messages INTEGER          Maximum message count
  --min-words INTEGER             Minimum total word count
  --since-session TEXT            Show sessions in same cwd after this session
                                  ID
  --since TEXT                    After date (ISO, 'yesterday', 'last week')
  --until TEXT                    Before date
  -l, -n, --limit INTEGER         Max results
  --offset INTEGER                Offset for paginated results
  --cursor TEXT                   Opaque keyset cursor from a previous
                                  response's next_cursor. Stable across
                                  archive growth for ranked search (#1268).
  --latest                        Most recent (= --sort date --limit 1)
  --sort [date|tokens|messages|words|longest|random]
                                  Sort by field
  --reverse                       Reverse sort order
  --sample INTEGER                Random sample of N sessions
  -o, --output TEXT               Output destinations: browser, clipboard,
                                  stdout (comma-separated)
  --json                          Shortcut for --format json. Disables color
                                  and progress for pipeable output. (#1689)
  -f, --format [markdown|json|ndjson|html|obsidian|org|yaml|plaintext|csv]
                                  Output format (for --latest, --stream, or
                                  verb output). `ndjson` emits one JSON
                                  document per line, streaming-friendly for
                                  shell pipelines and LLM tool-use harnesses.
  --explain                       Explain query DSL parsing and lowering
                                  instead of executing the query.
  --stream                        Stream output (low memory). Requires
                                  --latest or -i ID.
  --set TEXT...                   Set metadata key value
  --add-tag TEXT                  Add tags (comma-separated)
  --plain                         Force non-interactive plain output
  --no-daemon                     Run archive reads in-process instead of
                                  using the local daemon.
  -v, --verbose                   Verbose output
  --diagnose                      Explain CLI parser decisions on stderr
                                  before running. Useful when query-first
                                  dispatch surprises you: shows whether tokens
                                  were routed to a subcommand, an explicit
                                  query, or the strict command floor.
  --version                       Show the version and exit.
  --help                          Show this message and exit.

Commands:
  Search, read, and action workflows:
    find      Search the archive, then optionally run an...
    read      Read matched sessions (route to view/destination).
    select    Select one matched session or print candidate identities.
    mark      Mark selected sessions; review candidates under mark candidates.
    note      Capture a terminal memory candidate.
    analyze   Analyze matched sessions and named facet families.
    facets    Show global or scoped archive facet families.
    delete    Delete matched sessions.
    continue  Print or execute the harness command that resumes a session.
    Use `find QUERY then ACTION`; `facets` is the direct archive aggregate
    command.

  Setup, import, and evidence:
    config    Show resolved Polylogue configuration with...
    init      Detect chat sources and write a starter polylogue.toml.
    hooks     Install and monitor harness capture hooks.
    import    Import sessions from configured sources.
    demo      Seed and verify the deterministic demo archive.
    tutorial  Inspect first-run setup state.
    Use these for first-run setup, hook wiring, source import, demo archives,
    and onboarding checks.

  Reader and local UI:
    agents     Inspect agent coordination state.
    dashboard  Launch the terminal dashboard TUI.
    `agents` exposes JSON-first coordination views for agent loops;
    `dashboard` launches the terminal TUI.

  Operations and maintenance:
    status  Show daemon and archive status.
    ops     Run operational archive and daemon commands.
    `polylogue status` is the root shortcut for `polylogue ops status`; deeper
    maintenance stays under `ops`.

  Other commands:
    annotations  Import typed annotation batches.
    judge        Interactively triage candidate assertions.

Analyze Verb

Usage: polylogue analyze [OPTIONS] [COMMAND] [ARGS]...

  Analyze matched sessions: statistics, facets, and aggregates.

  Applies to the full result set by default (no cardinality restriction).
  Wraps aggregate and facet views over the matched session set.

  Examples:
      polylogue find 'repo:polylogue since:7d' then analyze
      polylogue find 'repo:polylogue since:7d' then analyze --count
      polylogue find 'repo:polylogue since:7d' then analyze --by origin
      polylogue find 'repo:polylogue since:7d' then analyze --by month
      polylogue find 'repo:polylogue' then analyze --facets
      polylogue find 'repo:polylogue' then analyze --by day --format json
      polylogue analyze --cost-outlook --plan claude-pro --format json
      polylogue analyze usage --format json

Options:
  --count                         Print only the matched-session count.
  --by [origin|month|year|day|action|tool|repo|work-kind]
                                  Group statistics by dimension
  --facets                        Show named facet families for the matched
                                  result set; cheap families are default.
  --cost-outlook                  Project the current billing cycle for a
                                  configured subscription plan.
  --postmortem                    Distilled postmortem bundle over the matched
                                  session scope (#2380).
  --portfolio                     Corpus-wide sanitized portfolio report over
                                  the matched scope (#2437).
  --plan TEXT                     Subscription plan name for --cost-outlook.
  --method [linear|trailing-7d-mean|eom-naive]
                                  Projection method for --cost-outlook.
  --no-idf                        With --facets, skip inverse-document-
                                  frequency weighting
  --include-deferred              With --facets, compute deferred detail
                                  families: repos, roles, material origins,
                                  message types, actions, flags.
  --json                          Shortcut for --format json.
  -f, --format [markdown|json|ndjson|html|obsidian|org|yaml|plaintext|csv]
                                  Output format (ndjson = one JSON document
                                  per row, streaming-friendly)
  -l, -n, --limit INTEGER         Max matched sessions before grouping
  --help                          Show this message and exit.

Commands:
  insights  Check and export derived insight materialization.
  pace      Analyze session pacing, gaps, and burstiness.
  tools     Analyze tool usage across sessions.
  turns     Analyze turn structure for one session.
  usage     Analyze provider usage events.

Read Verb

Usage: polylogue read [OPTIONS] [REF]

  Read matched sessions.

  Routes to the appropriate renderer based on --view and delivers the
  output to --to (terminal, stdout, browser, clipboard, or file).
  Use --views to inspect which options belong to each read view.

  Examples:
      polylogue --id abc123 read
      polylogue find id:abc then read --view messages
      polylogue find id:abc then read --view raw --format json
      polylogue find id:abc then read --to browser
      polylogue find 'repo:polylogue has:paste' then read --all --format ndjson
      polylogue find id:abc then read --view context --related-limit 5
      polylogue find 'cost tracking' then read --view context-image --max-sessions 5
      polylogue read --view context-image --project-repo github.com/Sinity/polylogue --since 2026-01-01
      polylogue read --views
      polylogue read --views --format json
      polylogue find 'repo:polylogue' then read --view temporal,chronicle --spec
      polylogue find id:abc then read --view neighbors --window-hours 48
      polylogue --latest read --view neighbors --format json
      polylogue find id:abc then read --view correlation --since-hours 4
      polylogue --latest read --view correlation --otlp --format json
      polylogue read session:abc123 --format json

Projection:
  -v, --view VIEW[,VIEW...]       What to render (summary, transcript,
                                  dialogue, messages, raw, context, context-
                                  image, neighbors, correlation, temporal,
                                  chronicle).  [default: summary]
  --render TEXT                   Render expression, e.g. layout:context-
                                  image,timestamps:include-
                                  available,format:markdown. Known keys:
                                  layout, timestamps, format, destination/to,
                                  out.
  --projection TEXT               Projection expression, e.g. max-
                                  tokens:4000,redact-paths:true,include-
                                  assertions:false. Known keys: max-tokens,
                                  redact-paths, include-assertions.
  --render-layout [standard|context-image]
                                  Render layout for the composed projection
                                  spec; defaults from --view.
  --timestamps [renderer-default|include-available|omit]
                                  Timestamp rendering policy for the composed
                                  projection spec; defaults from --view.
  --views                         List executable read-view profiles, formats,
                                  and options.
  --spec                          Print the composed
                                  selection/projection/render spec as JSON.

Delivery and format:
  --to [terminal|stdout|browser|clipboard|file]
                                  Output destination.  [default: terminal]
  --json                          Shortcut for --format json.
  -f, --format [csv|html|json|markdown|ndjson|obsidian|org|plaintext|text|yaml]
                                  Output format (where applicable).
  --out PATH                      File path for --to file.
  --fields TEXT                   Fields for JSON/YAML outputs (--all).

Cardinality and pagination:
  --all                    Read all matched sessions.
  -l, -n, --limit INTEGER  Max items to return.
  --offset INTEGER         Pagination offset.
  --first                  Read the first matched session only.

Context-image projection:
  --project-path TEXT     Filter by cwd prefix pattern (--view context-image).
  --project-repo TEXT     Filter by git repo URL or name (--view context-
                          image).
  --since TEXT            Start date, ISO 8601 (--view context-image).
  --until TEXT            End date, ISO 8601 (--view context-image).
  --context-origin TEXT   Source-origin filter (--view context-image).
  --query TEXT            Free-text query (--view context-image).
  --max-sessions INTEGER  Max sessions, 1-20 (--view context-image).
                          [default: 5]
  --max-tokens INTEGER    Bound accumulated output to a token budget; over-
                          budget segments are reported as omissions.
  --include-assertions    Include context-inject assertion claims in the
                          compiled context image.
  --no-redact             Do not redact filesystem paths (--view context-
                          image).

Context and neighbor views:
  --window-hours INTEGER   Neighboring time window around the seed session
                           (--view neighbors).  [default: 24]
  --related-limit INTEGER  Number of related sessions to include (--view
                           context).  [default: 5]

Correlation view:
  --repo-path TEXT                Git repository path for correlation (--view
                                  correlation). Defaults to the session's
                                  repo/cwd.
  --since-hours INTEGER           Hours before/after the session to scan for
                                  commits (--view correlation).  [default: 2]
  --confidence-threshold FLOAT    Minimum confidence for file-overlap commit
                                  detection (--view correlation).  [default:
                                  0.3]
  --github-api / --no-github-api  Cross-reference issue/PR refs with the
                                  GitHub API via gh CLI (--view correlation).
  --otlp                          Add OTLP span evidence to correlation output
                                  (--view correlation).

Other options:
  --full  Read a full single-session body for views that paginate.
  --help  Show this message and exit.

Select Verb

Usage: polylogue select [OPTIONS]

  Select one matched session or print bounded candidate identities.

Options:
  -n, --limit INTEGER RANGE  Max candidate sessions.  [default: 20; x>=1]
  --print [id|title|origin]  Field to print for selected or candidate
                             sessions.  [default: id]
  --json                     Shortcut for --format json.
  -f, --format [json]
  --help                     Show this message and exit.

Delete Verb

Usage: polylogue delete [OPTIONS]

  Delete matched sessions.

  Cardinality rules:
    --dry-run       Preview what would be deleted (no confirmation needed).
    --yes           Confirm deletion for a single matched session.
    --yes --all     Required when the query matches more than one session.

  Examples:
      polylogue find id:abc then delete --dry-run
      polylogue find id:abc then delete --dry-run --format json
      polylogue find id:abc then delete --yes
      polylogue find 'repo:polylogue since:7d' then delete --dry-run --all
      polylogue find 'repo:polylogue since:7d' then delete --yes --all

Options:
  --dry-run        Preview what would be deleted without deleting
  --yes            Confirm the deletion (required for actual deletion)
  --all            Delete all matched sessions (required when multiple match)
  --json           Shortcut for --format json.
  --format [json]  Output format. JSON emits a MutationResultPayload.
  --help           Show this message and exit.

Mark Verb

Usage: polylogue mark [OPTIONS] [COMMAND] [ARGS]...

  Mark query-result sessions with tags, notes, or durable marks.

  This owns session overlays only. Use `mark candidates` for assertion-
  candidate review; target-ref/web annotations are separate surfaces, not
  hidden here.

  Requires exactly one matched session unless --all is present.
  Use --first to act on the first match when the query is non-specific.

  Mark types: star, pin, archive (managed via --star/--unstar, --pin/--unpin,
  --archive/--unarchive).  Tags are free-form strings.  Notes are stored as
  durable annotations on the session.

  Examples:
      polylogue find id:abc then mark --tag-add reviewed
      polylogue find id:abc then mark --star --note "key insight"
      polylogue find id:abc then mark --unstar --tag-remove reviewed
      polylogue find id:abc then mark --pin
      polylogue find 'repo:polylogue since:7d' then mark --tag-add sprint --all

Options:
  --tag-add TAG     Add a tag to the matched session(s)
  --tag-remove TAG  Remove a tag from the matched session(s)
  --star            Star the matched session
  --unstar          Remove star from the matched session
  --pin             Pin the matched session
  --unpin           Remove pin from the matched session
  --archive         Archive-mark the matched session
  --unarchive       Remove archive-mark from the matched session
  --note TEXT       Add or update a note annotation
  --all             Apply to all matched sessions (default: singleton only)
  --first           Apply to the first matched session only
  --json            Shortcut for --format json.
  --format [json]   Output format. JSON emits a MutationResultPayload.
  --help            Show this message and exit.

Commands:
  candidates  Review assertion candidates for a selected session or...

Mark Candidate Assertions

Usage: polylogue mark candidates [OPTIONS] COMMAND [ARGS]...

  Review assertion candidates for a selected session or target ref.

  Candidate commands own review state and claim judgment: review, list,
  accept, reject, defer, or supersede candidate assertions. They do not apply
  ordinary session tags, stars, pins, archive marks, or notes.

Options:
  --help  Show this message and exit.

Commands:
  accept     Accept a candidate assertion into an active assertion.
  defer      Record a durable candidate assertion deferral.
  list       List candidate assertion claims.
  reject     Reject a candidate assertion with a durable reason.
  review     List candidate assertion review state and disabled actions.
  supersede  Supersede a candidate with an explicit active assertion.

Continue Verb

Usage: polylogue continue [OPTIONS]

  Print or explicitly execute a verified harness-resume command.

  Examples:
      polylogue find id:abc then continue
      polylogue find id:abc then continue --exec
      polylogue continue --candidates --repo /workspace/polylogue --recent polylogue/cli/query_verbs.py

Options:
  --exec                          Run the verified interactive resume command
                                  instead of printing it.
  --to [terminal|stdout|browser|clipboard|file]
                                  Output destination.  [default: terminal]
  --out PATH                      File path for --to file.
  --candidates                    Rank archived sessions that are likely
                                  continuation targets for a repository
                                  context.
  --repo TEXT                     Repository path for --candidates ranking.
  --cwd TEXT                      Current working directory for --candidates
                                  prefix matching.
  --recent TEXT                   Recently touched file path for --candidates.
                                  Repeatable.
  --limit INTEGER                 Maximum continuation candidates to return.
                                  [default: 10]
  --json                          Shortcut for --format json.
  -f, --format [json]             Reserved for compatibility; continue emits a
                                  shell command only.
  --help                          Show this message and exit.

Insights

Usage: polylogue ops insights [OPTIONS] COMMAND [ARGS]...

  Operate durable archive insight materialization.

Options:
  --help  Show this message and exit.

Commands:
  audit   Report per-product rigor profile across materialized insights...
  export  Export versioned archive-insight bundles.
  status  Report insight materialization coverage and readiness.

Operations

Usage: polylogue ops [OPTIONS] COMMAND [ARGS]...

  Run operational archive, daemon, auth, embedding, and maintenance commands.

Options:
  --help  Show this message and exit.

Commands:
  auth         Authenticate optional external services.
  backup       Create a timestamped durability-tier backup.
  debt         List archive work that needs operator attention.
  diagnostics  Run archive and session diagnostics.
  doctor       Run archive health checks and repairs.
  embed        Enable, preflight, and backfill the embedding pipeline.
  insights     Check and export derived insight materialization.
  maintenance  Preview and run maintenance backfill operations.
  reset        Reset local archive state.
  status       Show daemon and archive status.

Doctor

Usage: polylogue ops doctor [OPTIONS]

  Health check with optional maintenance and cleanup previews.

Options:
  -f, --format [json]             Output format
  -v, --verbose                   Show breakdown by origin
  --repair                        Run safe derived-data maintenance repairs
  --cleanup                       Run destructive archive cleanup for orphaned
                                  or empty persisted data
  --target [session_insights|message_type_backfill|orphaned_messages|empty_sessions|orphaned_attachments|orphaned_blobs|superseded_raw_snapshots]
                                  Limit maintenance to named targets such as
                                  session_insights, message_type_backfill,
                                  orphaned_messages, empty_sessions,
                                  orphaned_attachments, orphaned_blobs, or
                                  superseded_raw_snapshots
  --preview                       Preview maintenance without executing
                                  (requires --repair or --cleanup)
  --vacuum                        Reclaim unused space after maintenance
                                  (requires --repair or --cleanup)
  --deep                          Run SQLite integrity and expensive orphan
                                  scans (slow on large databases)
  --runtime                       Run environment and runtime verification
                                  checks
  --daemon                        Show daemon component status
  --blob, --blob-integrity        Verify blob store integrity (missing,
                                  orphaned, corrupt, and stale-lease blobs)
  --full                          Run full blob-integrity scan (requires
                                  --blob)
  --schemas                       Run raw-corpus schema verification (non-
                                  mutating)
  --artifact-coverage             Inspect durable artifact coverage
  --artifacts                     List durable artifact observations
  --cohorts                       Summarize durable artifact cohorts
  --schema-origin TEXT            Limit schema verification to archive origin
                                  (repeatable)
  --schema-provider TEXT          (DEPRECATED: Use --schema-origin instead.)
  --artifact-origin TEXT          Limit artifact coverage/listing/cohorting to
                                  effective origin (repeatable)
  --artifact-provider TEXT        (DEPRECATED: Use --artifact-origin instead.)
  --artifact-status TEXT          Limit artifact listing/cohorting to support
                                  status (repeatable)
  --artifact-kind TEXT            Limit artifact listing/cohorting to artifact
                                  kind (repeatable)
  --artifact-limit INTEGER        Limit artifact coverage/listing/cohorting to
                                  N observation rows
  --artifact-offset INTEGER       Start offset for artifact
                                  coverage/listing/cohorting  [default: 0]
  --schema-samples TEXT           Validation samples per raw payload: positive
                                  integer or 'all'  [default: all]
  --schema-record-limit INTEGER   Limit schema verification to N raw records
                                  (for chunked runs)
  --schema-record-offset INTEGER  Start offset for chunked schema verification
                                  [default: 0]
  --schema-quarantine-malformed   Mark malformed raw payloads as failed
                                  validation during schema verification
                                  (mutates DB)
  --help                          Show this message and exit.

Auth

Usage: polylogue ops auth [OPTIONS]

  Authenticate with external services (Google Drive for Gemini).

  Examples:
      polylogue ops auth           # Interactive OAuth for Google Drive
      polylogue ops auth --refresh # Force token refresh
      polylogue ops auth --revoke  # Revoke stored credentials

Options:
  --service TEXT  Auth service (default: drive)
  --refresh       Force token refresh
  --revoke        Revoke existing credentials
  --help          Show this message and exit.

Reset

Usage: polylogue ops reset [OPTIONS]

  Reset database, blob store, assets, cache, or auth state.

  By default, requires explicit flags to specify what to reset. Use --all to
  reset everything.

  Identity-preserving reset:
    --session ID  Tombstone a specific session (preserves user metadata)
    --source PATH      Tombstone all sessions from a source path
    --dry-run     Preview exact target rows before any tombstone write

Options:
  --index              Delete only the rebuildable index tier
  --database           Delete derived SQLite tiers, preserving durable
                       source.db and user.db
  --include-user-db    Also delete the irreplaceable user.db tier (tags,
                       annotations, marks, notes). Destructive.
  --include-source-db  Also delete durable source.db evidence. Refuses when
                       raw rows point at missing source files.
  --blob               Delete the content-addressed blob store
  --assets             Delete archived assets/attachments
  --cache              Delete search indexes, schemas, and cache
  --auth               Delete Google Drive OAuth tokens
  --all                Reset everything
  -y, --yes            Skip confirmation prompt
  --session TEXT       Tombstone a specific session by ID
  --source PATH        Tombstone all sessions from a source path
  --dry-run            Preview --session/--source identity-reset targets
                       without mutating anything
  --json               Shortcut for --format json (applies to
                       --session/--source).
  --format [json]      Output format for --session/--source identity resets.
                       JSON emits a MutationResultPayload.
  --help               Show this message and exit.

Config

Usage: polylogue config [OPTIONS] [COMMAND] [ARGS]...

  Show resolved Polylogue configuration with precedence sources.

Options:
  -f, --format [toml|json]  Output format.
  --show-layers             Show the layer source for each config key
                            (default/site/user/env/cli).
  --help                    Show this message and exit.

Commands:
  action-affordances  Print shared query-action affordance metadata as JSON.
  completions         Generate shell completion scripts.
  paths               Print canonical archive paths and filesystem topology.
  query-completions   Print shared query-builder completion metadata as...

Completions

Usage: polylogue config completions [OPTIONS]

  Generate shell completion scripts.

Options:
  --shell [bash|zsh|fish]  [required]
  --help                   Show this message and exit.

  Install:
    bash: add  eval "$(polylogue config completions --shell bash)"  to ~/.bashrc
    zsh:  add  eval "$(polylogue config completions --shell zsh)"   to ~/.zshrc
    fish: polylogue config completions --shell fish > ~/.config/fish/completions/polylogue.fish

  Dynamic completers cover: session IDs, origins/source-families,
  tags, repos, cwd prefixes, action categories and sequences, tool names,
  message types, retrieval lanes.

Paths

Usage: polylogue config paths [OPTIONS]

  Print canonical archive paths and filesystem topology.

  Reports the resolved archive root, database path, config file path, blob
  store root, and whether any bind mounts are detected.

Options:
  -f, --format [text|json]  Output format.
  --help                    Show this message and exit.

Dashboard

Usage: polylogue dashboard [OPTIONS]

  Launch the terminal dashboard TUI with explicit runtime evidence.

Options:
  --status              Print dashboard launch/readiness evidence without
                        starting the TUI.
  --format [text|json]  Output format for --status and launch evidence.
                        [default: text]
  --help                Show this message and exit.

Tutorial

Usage: polylogue tutorial [OPTIONS]

  Inspect first-run setup state and print the next concrete action.

  Each stage is idempotent — already-satisfied stages are marked ``[skip]``.
  Use ``--non-interactive`` to print the current state without prompting
  (suitable for scripts and CI).

Options:
  --non-interactive  Skip prompts; print the stage diagnostic and exit.
  --help             Show this message and exit.

Public Action Contracts

This section is generated from polylogue.operations.action_contracts.ACTION_CONTRACTS. It records the public action floor, not every utility command in the Click tree.

Published Machine Output Schemas

This section is generated from devtools.render_cli_output_schemas.SCHEMAS. The schema files live under docs/schemas/cli-output/.