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`, where 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, and, for OpenCode, provider and Sonnet/Opus model IDs. Once an auto-reinstall has run, it also shows 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. Slash-command dispatch preambles call these subcommands, and you can run them by hand to debug.

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. /code_review uses them internally, and you can pipe through them yourself.

codex stream

Read Codex CLI --json (JSONL) output on stdin and write readable lines to stdout. A pure pipe transformer with no config, no network, and 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, hyprlayer prints [warning] no turn.completed event — possible mid-stream disconnect on stderr. It treats a broken pipe on stdout (piping into head, say) as a clean exit.

The parser tolerates schema drift. It skips missing fields, malformed JSON lines, and unknown event types instead of failing.

hyprlayer telemetry

Manage anonymized usage analytics. Telemetry is on by default in anonymous mode. Hyprlayer records events to a local spool, then flushes them to PostHog in the background. It records stable event names, durations, outcomes, and a per-installation UUID, and never your source code, prompts, model output, file paths, or environment variables. 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. Hyprlayer keeps the local installation_id, 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, so running it against an already-enabled install does nothing.

hyprlayer telemetry on

telemetry init

Enable telemetry on a fresh installation. Hyprlayer runs it on first launch, so reach for it after you purge config or when you 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 hyprlayer auto-elevates profile-mapped corporate users to it
`--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 for 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`. Leaves other hooks in place
`uninstall`	Remove the hyprlayer Stop hook entry and nothing else
`status`	Print whether the hook is installed and the resolved `settings.json` path (`--json` for machine-readable)

hyprlayer ai configure installs the OpenCode plugin equivalent (telemetry-plugin.js) and re-installs it on agent-bundle updates. No separate command.

telemetry skill-start / skill-end

Skills use this low-level token pair to record one skill_run event with a duration. Skill scaffolding invokes them, so you never call them 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.