CLI Reference

Complete CLI command reference

hyprlayer thoughts

Manage the thoughts system.

thoughts init

Initialize thoughts for the current repository.

hyprlayer thoughts init [OPTIONS]

Option	Description
`--force`	Force reconfiguration even if already set up
`--directory <NAME>`	Specify the repository directory name (skips prompt)
`--profile <NAME>`	Use a specific thoughts profile
`--backend <KIND>`	Storage backend: `git` (default), `obsidian`, `notion`, `anytype`. See Storage Backends
`--vault-path <PATH>`	Obsidian vault path (required with `--backend obsidian --yes`)
`--vault-subpath <NAME>`	Subfolder within the Obsidian vault (default: `hyprlayer`)
`--parent-page-id <ID>`	Notion parent page ID (required with `--backend notion --yes`)
`--database-id <ID>`	Existing Notion database ID to reuse (skips lazy creation)
`--space-id <ID>`	Anytype space ID (required with `--backend anytype --yes`)
`--type-id <ID>`	Existing Anytype type ID to reuse (skips lazy creation)
`--api-token-env <NAME>`	Env var holding the Anytype API token (default: `ANYTYPE_API_KEY`). Ignored for `notion` — hyprlayer uses the agent’s Notion connector
`-y, --yes`	Run without interactive prompts
`--config-file <PATH>`	Path to config file

thoughts uninit

Remove thoughts setup from the current repository.

hyprlayer thoughts uninit [OPTIONS]

Option	Description
`--force`	Force removal even if not in configuration
`--config-file <PATH>`	Path to config file

thoughts sync

Manually sync thoughts to the thoughts repository.

hyprlayer thoughts sync [OPTIONS]

Option	Description
`-m, --message <MSG>`	Commit message for sync
`--config-file <PATH>`	Path to config file

thoughts status

Show status of the thoughts repository.

hyprlayer thoughts status [OPTIONS]

Option	Description
`--config-file <PATH>`	Path to config file

thoughts config

View or edit thoughts configuration.

hyprlayer thoughts config [OPTIONS]

Option	Description
`--edit`	Open configuration in editor
`--json`	Output configuration as JSON
`--config-file <PATH>`	Path to config file

thoughts profile create

Create a new thoughts profile.

hyprlayer thoughts profile create <NAME> [OPTIONS]

Option	Description
`--repo <PATH>`	Thoughts repository path
`--repos-dir <NAME>`	Repos directory name
`--global-dir <NAME>`	Global directory name
`--config-file <PATH>`	Path to config file

thoughts profile list

List all thoughts profiles.

hyprlayer thoughts profile list [OPTIONS]

Option	Description
`--json`	Output as JSON
`--config-file <PATH>`	Path to config file

thoughts profile show

Show details of a specific profile.

hyprlayer thoughts profile show <NAME> [OPTIONS]

Option	Description
`--json`	Output as JSON
`--config-file <PATH>`	Path to config file

thoughts profile delete

Delete a thoughts profile.

hyprlayer thoughts profile delete <NAME> [OPTIONS]

Option	Description
`--force`	Force deletion even if in use
`--config-file <PATH>`	Path to config file

hyprlayer ai

Manage AI tool configuration.

ai configure

Configure AI tool and install agent files.

hyprlayer ai configure [OPTIONS]

Option	Description
`--force`	Force reconfiguration even if already set up
`--config-file <PATH>`	Path to config file

ai status

Show current AI tool configuration: agent tool, install location, (for OpenCode) provider and Sonnet/Opus model IDs, and — once an auto-reinstall has run — the cached short bundle SHA and a humanized last-check timestamp (“4 hours ago”). Pass --json for a machine-readable payload that includes the full agentsInstalledSha and the raw lastAgentCheck Unix timestamp.

hyprlayer ai status [OPTIONS]

Option	Description
`--json`	Output as JSON
`--config-file <PATH>`	Path to config file

ai reinstall

Reinstall AI agent files.

hyprlayer ai reinstall [OPTIONS]

Option	Description
`--config-file <PATH>`	Path to config file

hyprlayer storage

Query and update the active thoughts storage backend. These subcommands are primarily called by slash-command dispatch preambles, but are usable interactively for debugging.

storage info

Show the resolved backend, settings, and the unified schema contract for the current repository.

hyprlayer storage info [OPTIONS]

Option	Description
`--json`	Emit a structured JSON payload slash commands parse
`--config-file <PATH>`	Path to config file

The JSON payload includes backend, settings (backend-specific), mappedName, projectPath, and the full schema array documenting the 10 metadata fields every thought carries. See Storage Backends.

storage set-database-id

Persist the Notion database ID after a slash command lazily creates it via MCP. Errors if the active backend is not notion.

hyprlayer storage set-database-id <ID>

storage set-type-id

Persist the Anytype type ID after a slash command lazily creates it via MCP. Errors if the active backend is not anytype.

hyprlayer storage set-type-id <ID>

hyprlayer codex

Utility subcommands for working with the OpenAI Codex CLI. Used internally by /code_review but available for ad-hoc piping.

codex stream

Read Codex CLI --json (JSONL) output on stdin and write readable lines to stdout. Pure pipe transformer — no config, no network, no auth.

codex exec "<prompt>" --json | hyprlayer codex stream [OPTIONS]

Option	Description
`--no-thinking`	Suppress `[codex thinking]` lines (reasoning events)
`--no-tool-calls`	Suppress `[codex ran]` lines (command execution events)

Output:

SESSION_ID:<thread_id> — emitted once when codex opens a thread
[codex thinking] <text> — reasoning events (suppress with --no-thinking)
[codex ran] <command> — tool calls (suppress with --no-tool-calls)
Agent messages — printed verbatim
tokens: <total> — input + output token total at end of turn

A turn.failed event prints [codex turn.failed] <error> to stderr. If the stream ends without a turn.completed or turn.failed event, a [warning] no turn.completed event — possible mid-stream disconnect is emitted on stderr. Broken-pipe on stdout (e.g. piping into head) is treated as a clean exit.

The parser is permissive about schema drift: missing fields, malformed JSON lines, and unknown event types are silently skipped rather than fatal.

hyprlayer telemetry

Manage anonymized usage analytics. Telemetry is on by default in anonymous mode and is recorded to a local spool, then flushed in the background to PostHog. No source code, prompts, model output, file paths, or environment variables are recorded — only stable event names, durations, outcomes, and a per-installation UUID. See Telemetry for the full data contract and the privacy model.

telemetry status

Show the current mode, endpoint, installation ID, and pending spool depth.

hyprlayer telemetry status [--json]

Option	Description
`--json`	Emit a structured JSON payload (mode, installation_id, org_id, endpoint, spool depth)
`--config-file <PATH>`	Path to config file

telemetry off

Disable telemetry. The local installation_id is preserved so re-enabling later doesn’t double-count this machine.

hyprlayer telemetry off

On installations enrolled in a corporate org (via --org-id at init time or a HYPRLAYER_ORG_ID GitHub variable), this command is locked and returns a non-zero exit with the locked-mode error message; corporate mode requires telemetry to stay on.

telemetry on

Re-enable telemetry in anonymous mode. Idempotent — safe to run when already enabled.

hyprlayer telemetry on

telemetry init

Enable telemetry on a fresh installation. Auto-run on first launch; you only need this if you previously purged config or want to tag a corporate enrollment.

hyprlayer telemetry init [OPTIONS]

Option	Description
`--mode <anonymous\|identified>`	`anonymous` (default) emits only the per-installation UUID. `identified` attaches a stable user handle and is auto-elevated for profile-mapped corporate users
`--api-key <KEY>`	Override the bundled PostHog public API key
`--org-id <ID>`	Tag events with an organization identifier and lock the install in corporate mode
`--config-file <PATH>`	Path to config file

telemetry flush

Drain the local event spool and POST events to PostHog in the foreground. Useful for CI runners and for verifying connectivity.

hyprlayer telemetry flush

telemetry purge

Delete the local event spool without sending. Does not change the on/off mode.

hyprlayer telemetry purge

telemetry config

Inspect or override the resolved telemetry config — useful for self-hosted PostHog endpoints or pulling per-org keys from the thoughts repo’s GitHub variables.

hyprlayer telemetry config [OPTIONS]

Option	Description
`--show`	Print the effective resolved config
`--api-key <KEY>`	Set a sticky PostHog API key override
`--org-id <ID>`	Set a sticky organization identifier
`--reset`	Clear manual overrides; fall back to default / GitHub-variable resolution
`--refresh`	Force re-pull of `HYPRLAYER_TELEMETRY_KEY` / `HYPRLAYER_ORG_ID` from the thoughts repo’s GitHub variables
`--config-file <PATH>`	Path to config file

telemetry hook

Manage the Claude Code Stop-hook that records per-skill token totals.

hyprlayer telemetry hook <install|uninstall|status> [OPTIONS]

Subcommand	Description
`install`	Install (or refresh) the hyprlayer Stop hook in `~/.claude/settings.json`. Other hooks are preserved
`uninstall`	Remove just the hyprlayer Stop hook entry
`status`	Print whether the hook is installed and the resolved `settings.json` path (`--json` for machine-readable)

The OpenCode plugin equivalent (telemetry-plugin.js) is installed automatically by hyprlayer ai configure and re-installed on agent-bundle updates — no separate command needed.

telemetry skill-start / skill-end

Low-level token pair used by skills to record one skill_run event with a duration. Normally invoked by skill scaffolding; you don’t need to call these by hand.

TOKEN=$(hyprlayer telemetry skill-start --skill create_plan)
# ... skill runs ...
hyprlayer telemetry skill-end --skill create_plan --session "$TOKEN" --outcome success

--outcome accepts success, failure, or aborted. --error-class attaches a stable error category (no message text) on failure paths.