HypAware
Talk to an engineer

HypAware CLI command reference

Documentation

This reference documents the visible commands shipped with HypAware. It uses the canonical hyp spelling. The hypaware binary accepts the same arguments.

For installation, upgrade, recovery, and task-oriented workflows, see Use the HypAware CLI.

On this page

Read command syntax

In syntax blocks, angle brackets mark required values and square brackets mark optional values. Replace uppercase values in examples with values for your environment. Don't type the brackets.

Most usage errors return exit code 2. Operational failures usually return exit code 1. A command can define a more specific contract, which this page notes where stable. Use --help on any visible command to read the help for your installed version.

Plugin-owned commands

Core commands are always registered. Plugin-owned commands are registered only when their plugin is active in the effective configuration. They also appear in top-level and group help only while active.

This reference identifies each plugin-owned family:

  • session ...: @hypaware/ai-gateway.
  • client claude-account ...: @hypaware/claude-account.
  • client claude-desktop ...: @hypaware/claude-desktop.
  • graph ... and query graph neighbors: @hypaware/context-graph.
  • query vector ... and vector status: @hypaware/vector-search.
  • enrichment ...: @hypaware/context-graph-enrich.

Hidden credential and client-hook machine contracts aren't user commands and aren't documented here. Hidden Gas City routes are also excluded because their process-memory changes don't persist yet.

Set up and inspect HypAware

hyp setup

hyp setup [preset] [flags]

Runs the guided setup, applies a named plugin preset, or performs an unattended configuration. It can write or replace the local configuration, install the daemon, attach clients, install client assets, and import history. --dry-run writes nothing. --force backs up and replaces an existing configuration. Important options include repeatable --source and --client, --export, --retention-days, --from-file, --no-daemon, and --bin.

hyp setup --source claude --client claude --export keep-local --yes

Success returns 0. Invalid arguments or a refused overwrite return 2; installation or configuration failures return 1.

hyp status

hyp status [--json]

Collects one read-only health snapshot without activating plugins. It reports configuration, daemon, active plugins, sources, sinks, clients, cache, recent errors, first-sync state, and repair commands. For Claude, it also reports OTEL attach mode, configured and live listener endpoints, endpoint drift, recorder activity, and capture health. Use --json for the stable machine form.

hyp status --json

hyp ask

hyp ask ["question"] [--list]

With no argument, asks the one question worth asking first: which skill would be the most useful to add. HypAware measures the last 30 days of recorded history itself, writes the evidence into one folder under the system temp directory (rewritten each time), and starts an attached AI client in that folder to answer with one skill. If more than one attached client could be started, it asks which. With a question, skips the gather and starts the client on that question in the current directory. The client takes over the terminal. --list prints the question and launches nothing. An empty cache, a declined selection, or list-only use succeeds. No launchable client, no gatherable evidence, or a process-start failure returns 1.

hyp ask "which sessions changed the authentication module"

Query recorded data

hyp query <subcommand> [args...]

Use hyp query --help to list the query subcommands available in the current configuration:

hyp query --help

Typed query commands accept shared rendering controls such as --format, --output, --max-cell, and --max-bytes. They also accept --refresh never|auto|always for local cache refresh and --remote [TARGET] for remote execution when the command is a remote-capable typed verb. You can't request an explicit local refresh and remote execution together. With --remote, an operator can add --org <label|*> to read one org by label or every org the account may read. It is rejected without --remote, and the remote records each such read in that org's audit trail.

hyp query overview

hyp query overview [--json] [--sql] [--days <n>] [--include-local-only]

Prints a local summary of token use, models, daily activity, repositories, and tools. It chooses a bounded date window unless you set --days. --sql prints the underlying queries. --include-local-only can place private local content in output, so use it only in a context that won't be recorded or shared.

hyp query overview --days 30

The command is read-only and local-only. It returns 1 if no AI traffic dataset is registered.

hyp query sql

hyp query sql <sql> [--include-local-only] [--format <fmt>] [--output <file>] [--max-cell <n>] [--max-bytes <n>] [--remote <target> [--org <label|*>]]

Runs one read-only SELECT statement against registered datasets. Local queries refresh the cache automatically by default and hide local-only rows from callers that can sync. A bare --remote selects the default target; --remote TARGET selects a named target. Formats are table, json, jsonl, and markdown.

hyp query sql "select count(*) as rows from ai_gateway_messages"

Invalid or non-read-only SQL returns a usage error. Query, remote, or output failures return 1.

hyp query grep

hyp query grep <pattern> [--regex] [--session-id <id>] [--chain-id <id>] [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--limit <n>] [--include-local-only] [--format <fmt>] [--output <file>] [--max-cell <n>] [--max-bytes <n>] [--remote <target> [--org <label|*>]]

Provided by the bundled @hypaware/grep plugin. New hyp setup capture configurations include it; existing client configurations gain it automatically on startup, preserving explicit enabled: false entries. The migration backs up the local config before writing. With a read-only config, search remains available for the current process and a warning reports that persistence failed.

Searches recorded ai_gateway_messages text without SQL. The pattern is a case-insensitive substring by default, or a regular expression with --regex. Hits arrive newest first, one row per matched column, each carrying session_id, message_id, and part_id locators you can pivot into hyp query sql. The default limit is 50 and the ceiling is 1000: a larger value clamps to the ceiling, and a value the flag cannot use at all (0, negative, fractional) is a usage error rather than a quiet 50.

Only these columns are searched: content_text, tool_name, session_id, conversation_id, agent_id, model, cwd, git_branch, git_remote. Zero hits is not evidence the text is absent from system_text, tools, tool_args, attributes, or raw_frame; read those with hyp query sql.

Local search scans the cache directly without building or reading indexes. Narrow the date range on large histories to reduce scan work. A remote target keeps its own hypgrep indexes. Local-only rows are withheld with a count on stderr, exactly as in SQL, and --include-local-only is the same informed-consent override. --remote TARGET runs the same search remotely, which enforces its own visibility: --regex is operator-only there, and --include-local-only is rejected.

hyp query grep "connection refused" --from 2026-08-01 --format json

An unknown flag returns a usage error, and so does any --from/--to that cannot select a day: one not shaped YYYY-MM-DD, or a --from later than the --to. Both would otherwise prune every file and render an empty answer that reads like "nothing is recorded". A pattern the search cannot use is a usage error too: an invalid regular expression under --regex, or one longer than 1024 characters. Those day and pattern checks are local: --remote hands the request to the remote, which applies its own argument rules and its own codes (the flag-shape and --limit checks still run locally, before the request is sent). Search or output failures return 1.

hyp query schema

hyp query schema <dataset>

Prints the registered columns for one local dataset. It doesn't activate a remote target.

hyp query schema ai_gateway_messages

hyp query graph neighbors

Plugin: @hypaware/context-graph.

hyp query graph neighbors <node> [--depth <depth>] [--type <type>] [--edge-type <edge_type...>] [--direction out|in|both] [--limit <limit>] [--include-local-only] [--format <fmt>] [--output <file>] [--max-cell <n>] [--max-bytes <n>] [--remote <target> [--org <label|*>]]

Resolves a node ID, natural key, or label, then walks the activity graph in breadth-first order. Use --type to resolve an ambiguous seed, repeat --edge-type to restrict relations, and use --direction to control edge direction. The default depth is 1, direction is both, and limit is 100. The parser also accepts --json for the command's structured result.

hyp query graph neighbors src/core/cli/dispatch.js --type File --depth 2 --direction in

This command is read-only and supports remote execution. An unresolved or ambiguous seed returns 1; invalid arguments return 2. If the graph is empty, build it with hyp graph project.

Plugin: @hypaware/vector-search. The visible hyp query vector group lists its search subcommand:

hyp query vector <subcommand> [args...]

hyp query vector --help

Search syntax is:

hyp query vector search <query> [--index <name>] [--dataset <name>] [--top-k <n>] [--no-refresh] [--format <fmt>]

Embeds the query and searches configured local vector shards. Automatic refresh can write index data and call the configured embedder. --no-refresh uses the shards as they are. This command is local-only; it doesn't accept remote execution.

hyp query vector search "daemon restart failure" --top-k 5 --format json

Render and manage reports

hyp report <subcommand> [args...]

Use hyp report --help to list report operations:

hyp report --help

render is local. The other report commands use a remote target and resolve the default remote if --remote is omitted. Publishing and deletion require a write-capable credential.

hyp report render

hyp report render [<dir>] [--no-refresh-assets]

Builds a static HTML site from a local reports tree. The directory defaults to ~/hypaware-reports. It replaces the derived html/ directory, preserves source Markdown and assets/theme.css, and refuses an empty source tree. --no-refresh-assets also preserves the other copied assets.

hyp report render ~/hypaware-reports

hyp report publish

hyp report publish <file-or-dir> --kind <kind> --period <period> [--title <title>] [--org <org>] [--remote <target>]

Uploads Markdown for the remote to render. A single file must be .md or .markdown, sent as text/markdown. A folder must contain report.md at its root and may otherwise contain only usage.md, work.md, health.md, and recommendation-<slug>.md (slug: lowercase [a-z0-9][a-z0-9-]*); HTML, images, client assets, subdirectories, and symlinks are rejected before any upload. The remote renders the HTML; there is no local render step in the publish path. The remote identifies repeat uploads by content hash. --org applies only to an operator credential that can name an organization.

hyp report publish ./hypaware-report-2026-08-01-to-2026-08-31 --kind usage-review --period 2026-08

hyp report list

hyp report list [--kind <kind>] [--period <period>] [--limit <n>] [--before <publishedAt>] [--org <org>] [--json] [--remote <target>]

Lists the newest reports visible to the selected organization. An empty list succeeds. Each report's recommendations follow its line, one per line, as the minted id, the recommendation-<slug> page the id names, and the page's title, with its thesis on the line below. The page is the artifact path hyp report get takes. A remote that does not read the page's opening at publish, or a report published before it did, lists the id and page alone. --json prints the records whole, recommendations included.

  2026-08-24T09:00:00.000Z	usage-review/2026-W34	REPORT_ID	48213 bytes	Usage review
      hyprec-0123456789abcdef	recommendation-batch-the-retries	Batch the retries
          Every retry is its own call, 506 times a month. One queue fixes it.
      hyprec-fedcba9876543210	recommendation-tenant-check

hyp report list --kind usage-review --limit 10 --json

hyp report get

hyp report get <kind> <period> <id> [path] [--output <file>] [--org <org>] [--remote <target>]
hyp report get <rec-id> [--output <file>] [--org <org>] [--remote <target>]

Fetches a report's entry document or one artifact. Without --output, it writes the exact bytes to standard output, including binary artifact bytes. A path with no extension of its own is tried as given and then as .md and .html, so the recommendation-<slug> stem hyp report list prints fetches that page without spelling out how it was published.

hyp report get usage-review 2026-W34 REPORT_ID --output ./usage-review.html

Replace REPORT_ID with the ID from hyp report list.

Given a recommendation id instead (hyprec- and sixteen hex characters, the id hyp report list prints under each report), it resolves the id to its report and page and prints that page (Markdown, or HTML when the report was published without it) with a Citations from the report record tail: the turns the page cites as evidence:N, numbered to match, and the queries the report ran to reach the recommendation, verbatim in sql blocks. This is the read to make from inside an AI client session when asked to fix a recommendation by id.

hyp report get hyprec-0123456789abcdef

hyp report fix

hyp report fix [id] [--kind <kind>] [--period <period>] [--limit <n>] [--org <org>] [--remote <target>]

Starts an attached AI client on one recommendation, in the current directory. The id is the one hyp report list prints under each report. HypAware resolves it to its report, checks the recommendation page still exists, and starts the client with instructions to read it through hyp report get <rec-id> and make the change in the current repository. Nothing is written to disk. The client takes over the terminal and nothing is pre-authorised: the client asks before running the read.

With no id on a terminal, it asks in two steps: first which report, newest first, each with its publish date and how many recommendations it carries (a report with none is not offered); then which of that report's recommendations, labelled by the page's title and described by its thesis when the remote lists them, else by the page name. Escape on the second list returns to the first. --kind, --period and --limit narrow which reports are offered. Without a terminal the id is required. If more than one attached client could be started, it asks which. A declined pick succeeds. An unknown id, no launchable client, or a process-start failure returns 1.

hyp report fix hyprec-0123456789abcdef
hyp report fix --kind usage-review

hyp report delete

hyp report delete <kind> <period> <id> [--yes] [--org <org>] [--remote <target>]

Warning: This operation permanently deletes the report and its artifacts for every member of the organization. It prompts on a terminal. A non-interactive call without --yes refuses with exit code 2.

hyp report delete usage-review 2026-W34 REPORT_ID

Replace REPORT_ID with the reviewed report ID. Avoid --yes during manual work so you can confirm the target.

Send data now

hyp sync

hyp sync [instance] [--history <client>] [--yes] [--dry-run]

Prints a destination and exclusion plan, confirms it, then forces the selected sink or every configured sink to export. --dry-run sends nothing. On a newly enrolled machine, an interactive all-destination sync can release the first-sync review hold early. A single-instance sync can't release that hold.

--history <client> is a separate mode: it previews and, after its own confirmation, replays that client's locally retained history to the destinations that support a replay, leaving the ordinary sink watermarks untouched. The client must already be syncing (hyp privacy client <client> sync), and a replay cannot release the first-sync review hold.

hyp sync --dry-run

Any sink failure returns 1. While the first-sync review window is open, a run that finds no configured destination returns 3: nothing was sent, and the window still stands. --dry-run and --history still return 0 there, as they do with no window open: neither can end the window, so neither has an early release to report. Avoid --yes until you have reviewed the plan.

Control the current session

Plugin: @hypaware/ai-gateway. Use hyp session --help when the plugin is active:

hyp session <subcommand> [args...]

hyp session --help

If you omit the session ID, HypAware derives it from a supported Claude Code or Codex context. It refuses rather than guessing. The in-memory state disappears when the daemon restarts, and a fork has a new session ID.

hyp session status

hyp session status [session-id] [--json]

Checks every live recorder that advertises the shared session-control route. Exit 0 means every recorder confirms that the session is ignored. Exit 1 means at least one recorder confirms that it is recording. Exit 3 means the result is unknown; assume the session is being recorded.

hyp session status

Folder policy remains independent. Use hyp privacy show to inspect it.

hyp session ignore

hyp session ignore [session-id] [--json]

Adds the exact session ID to every available recorder's in-memory drop set. This stops future capture only. It doesn't delete existing rows. The Claude telemetry listener deletes ignored-session bodies from its transient spool.

hyp session ignore

hyp session unignore

hyp session unignore [session-id] [--json]

Removes the exact session ID from the live recorder sets. Folder policy can still prevent recording.

hyp session unignore

Manage AI clients and history

hyp client <subcommand> [args...]

Use hyp client --help to list core and active-plugin client operations:

hyp client --help

hyp client status

hyp client status [client] [--json]

Projects the client portion of the overall status snapshot. It reports whether each client is configured, attached, attachable, recently active, and healthy. For Claude, it includes OTEL endpoint drift and recorder health.

hyp client status claude --json

hyp client attach

hyp client attach [client] [--dry-run] [--json]

Short form: hyp attach, which the guides use.

Writes only HypAware-managed client settings and installs registered skills and subagents. Repeating the command is a no-op. Claude Code uses its OTEL settings and requires version 2.1.193 or later. Gateway-backed clients require an active gateway configuration. OpenCode installs a HypAware-owned plugin in its shared CLI/Desktop config home and requires no gateway. --dry-run writes nothing.

hyp client attach claude --dry-run

Codex attach covers both Codex CLI and Codex Desktop because they share ~/.codex/config.toml and ~/.codex/sessions.

OpenCode attach likewise covers CLI and Desktop because they share the same XDG config home and session store.

hyp client detach

hyp client detach [client] [--dry-run] [--purge] [--json]

Short form: hyp detach, which the guides use.

Replays the on-disk undo marker and removes only managed settings. It keeps recordings. Claude telemetry detach removes the managed OTEL settings and sweeps the raw-body spool. For a legacy or other proxy attach, --purge also removes the local interception CA and its keychain trust. --dry-run writes nothing. The command doesn't ask for confirmation.

Warning: Use --purge only when you intend to remove the interception CA and its keychain trust. You need to approve keychain changes again if you later reattach through a proxy.

hyp client detach codex --dry-run

Client history commands

Use the history group to inspect providers before you import:

hyp client history <subcommand> [args...]

hyp client history --help

hyp client history import

hyp client history import [provider...] [--since <iso>] [--until <iso>] [--retention-days <n>] [--dry-run] [--json]

Scans selected providers, materializes records into live datasets, appends rows, and flushes the cache. Provider failures don't stop sibling providers. --dry-run scans without writing.

hyp client history import claude codex --since 2026-08-01T00:00:00Z --dry-run

hyp client history plan

hyp client history plan [provider...] [--retention-days <n>] [--json]

Calls provider planning hooks without importing rows. The command is read-only. A provider planning failure can appear in output even when the overall command returns 0, so inspect every provider row.

hyp client history plan claude --json

hyp client history providers

hyp client history providers [--json]

Lists every registered backfill provider, not only providers selected as configuration defaults.

hyp client history providers --json

Scheduled recovery sweeps and backfill.window_days

Some adapters rerun their history provider on a schedule, so history the live capture lane never saw is recovered without you running hyp client history import by hand. @hypaware/claude (which also serves Claude Desktop) and @hypaware/openclaw (its transcript sweep, Lane B) both sweep every five minutes by default.

A positive backfill.window_days on a plugin entry bounds that scheduled sweep as well as the join-time import. This is deliberate: a window_days set only to keep the first import small also caps every later recovery, so a session older than the window is never swept up, OpenClaw's Lane B included. Nothing is removed from disk. The history is only left unimported, and widening or dropping window_days lets the next sweep take it.

{ "name": "@hypaware/openclaw", "config": {
  "backfill": { "window_days": 30 }
} }

With no window_days, the sweep falls back to the cache retention window: query.cache.retention.default_days if set, otherwise 90 days. A default_days of 0 is the open window rather than a zero-day one, so a sweep that falls back to it scans all history.

Setting the same block's on_join to false stops @hypaware/claude's scheduled sweep as well as its join-time import: that adapter contributes no schedule at all when the flag is off. It does not stop @hypaware/openclaw's. That adapter contributes its Lane B schedule unconditionally, so an OpenClaw entry with backfill.on_join: false still sweeps on its sweep_cron cadence; today the only way to bound it is window_days.

Client skill commands

The visible hyp client skills group contains the install command:

hyp client skills <subcommand> [args...]

hyp client skills --help

hyp client skills install

hyp client skills install [--client <name>]

Replaces registered skill and subagent copies for one client, or for all eligible clients when you omit --client. It requires a home directory and is safe to repeat.

hyp client skills install --client codex

Claude account commands

Plugin: @hypaware/claude-account. These commands are available only when the plugin is active and configured for the intended credential mode.

hyp client claude-account <subcommand>

hyp client claude-account login

hyp client claude-account login

Starts an interactive Claude subscription OAuth flow. It opens a browser with a loopback callback and offers pasted-code fallback. It stores a refreshable credential in permission-restricted plugin state. Organization-key mode refuses because it doesn't need subscription sign-in.

hyp client claude-account login

hyp client claude-account logout

hyp client claude-account logout

Removes the locally stored subscription credential. It doesn't revoke the credential at Anthropic or remove organization-key configuration.

hyp client claude-account logout

hyp client claude-account status

hyp client claude-account status

Reports the credential mode and whether a usable credential is present. A missing, expired, unreadable, or unresolved credential returns 1.

hyp client claude-account status

Claude Desktop commands

Plugin: @hypaware/claude-desktop.

Desktop capture is transcript-only by default. Select Claude Desktop in hyp setup; the daemon reruns the Claude history provider every five minutes. This needs no Claude account credential and makes no changes to the Desktop app.

Selecting Claude Desktop also enables Claude Code capture: the capture set below includes @hypaware/claude, the shared transcript reader, so a Desktop-only selection imports existing Claude Code CLI history from ~/.claude/projects under client_name = 'claude' and may attach Claude Code by updating ~/.claude/settings.json. Set attach.on_join: false on the @hypaware/claude entry to withhold the attach; backfill.on_join: false (below) withholds the history import.

The resulting config has this capture set:

{
  "plugins": [
    { "name": "@hypaware/ai-gateway", "config": { "upstreams": [] } },
    { "name": "@hypaware/claude" },
    { "name": "@hypaware/claude-desktop" }
  ]
}

Tune the timer in the Claude plugin config if needed:

{ "name": "@hypaware/claude", "config": {
  "backfill": { "sweep_cron": "*/10 * * * *" }
} }

The same block's window_days, if set, bounds this scheduled rerun as well as the join-time import: see "Scheduled recovery sweeps and backfill.window_days" above.

To turn the schedule off, set the same block's on_join to false. That is the existing opt-out from automatic history import, and it now withholds the scheduled rerun as well as the join-time one; sweep_cron chooses a cadence and has no "never" value.

{ "name": "@hypaware/claude", "config": {
  "backfill": { "on_join": false }
} }

The subcommands below operate the older managed third-party-inference route. They are optional experiments, not prerequisites for transcript capture. They require @hypaware/claude-account; without that capability they return a repair message while the scheduled transcript lane continues normally.

hyp client claude-desktop <subcommand> [args...]

hyp client claude-desktop install

hyp client claude-desktop install [--yes] [--print-commands]

Optionally runs the attended macOS live-route setup: explains the changes, signs in if needed, writes the credential helper, backs up and clears stale dialog residue, writes the root-owned managed-preferences property list through sudo, and asks you to restart Claude Desktop. It is resumable and idempotent. --print-commands changes nothing. --yes accepts the explained local changes but doesn't bypass browser or sudo authentication.

hyp client claude-desktop install --print-commands

hyp client claude-desktop status

hyp client claude-desktop status

Reports the resolved endpoint, credential mode, helper path, models, and bundle ID. A missing helper returns 1, and so does a generated helper whose baked interpreter or CLI path has rotted away, which prints STALE and names the re-run. This command doesn't verify the installed property list.

hyp client claude-desktop status

hyp client claude-desktop verify

hyp client claude-desktop verify

Checks that the managed property list is present and current, that the credential wrapper it names is present and still runnable, and that stale dialog residue is cleared. Those automatic checks determine the exit code. It also prints a manual in-app capture check, which doesn't affect the exit code.

hyp client claude-desktop verify

hyp client claude-desktop profile

hyp client claude-desktop profile [--plist] [--out <path>]

Renders a secret-free managed third-party-inference profile as JSON, or as a managed-preferences property-list dictionary with --plist. --out writes the result to a file. Install the helper first.

hyp client claude-desktop profile --plist --out ./claude-desktop.plist

hyp client claude-desktop install-helper

hyp client claude-desktop install-helper [--path <path>]

Writes the executable, no-argument credential wrapper that the Desktop profile references. The default location is in plugin state and outside protected desktop directories.

hyp client claude-desktop install-helper

Control privacy

hyp privacy <subcommand> [args...]

Use hyp privacy --help to list privacy operations:

hyp privacy --help

Directory classes are sync, local-only, and ignore. A policy marking is prospective; it doesn't delete rows already in the cache. Use purge only when you intend to delete existing local data.

hyp privacy show

hyp privacy show [path] [--json]

Resolves the governing class and source for a path, which defaults to the current directory. It also reports a best-effort residual cache count.

hyp privacy show . --json

hyp privacy set

hyp privacy set <path> sync|local-only|ignore

Upserts an exact machine-local path marking. It doesn't write a dotfile or delete rows.

hyp privacy set ./private-research local-only

hyp privacy unset

hyp privacy unset <path> [sync|local-only|ignore]

Removes machine-local entries governing the path. Add a class to remove only entries of that class. The operation is idempotent and doesn't delete rows.

hyp privacy unset ./private-research local-only

hyp privacy list

hyp privacy list [--json]

Lists machine-local path and client policy plus the new-folder prompt preference. It can't globally enumerate .hypignore files; use hyp privacy show PATH for a specific path.

hyp privacy list --json

hyp privacy ignore

hyp privacy ignore [path]

Writes a shareable .hypignore file at the explicit path or repository root. Use hyp privacy set <path> sync|local-only|ignore for machine-local markings and hyp privacy show [path] to report without writing.

hyp privacy ignore ./customer-data

hyp privacy unignore

hyp privacy unignore [path]

Removes the nearest governing .hypignore. Use hyp privacy unset <path> to remove machine-local markings. It does not remove cached rows.

hyp privacy unignore ./customer-data

hyp privacy client

hyp privacy client [<name>] [sync|local-only] [--json]

Lists or changes per-client export policy. local-only withholds future rows from remote sync. Returning to sync affects future rows only: the policy flip itself uploads nothing that was withheld. To upload that retained history, run the separate, separately confirmed hyp sync --history <client>. A client required by central configuration can't opt out.

hyp privacy client codex local-only

hyp privacy folders

hyp privacy folders [ask|sync] [--json]

Reports or changes whether unclassified folders sync by default or prompt once for classification. Existing markings and .hypignore files don't change.

hyp privacy folders ask

hyp privacy purge

hyp privacy purge <path> | --session <id> | --ignored | --all [--yes] [--json]

Warning: This operation permanently deletes matching rows from this machine's local cache. Select exactly one target. It never contacts a sink or HypAware Cloud and can't retract exported copies. Every form also sweeps the Claude raw-body spool so pending bodies can't recreate deleted rows. A terminal prompts for confirmation; a non-interactive call requires --yes.

hyp privacy purge --session SESSION_ID

Replace SESSION_ID with the reviewed session ID. Avoid --yes during manual work.

Connect to or leave HypAware Cloud

hyp join

hyp join <url> [token] [--token-file <path>] [--bin <path>] [--no-daemon]

Validates the URL and enrollment token, writes a permission-restricted central seed layer, and installs or restarts the daemon. The full organization configuration arrives later. Local configuration and history remain. --no-daemon writes only the seed and leaves service installation as an explicit next step.

hyp join https://hyp.example.com --token-file ./enrollment-token

Prefer --token-file or standard input. A positional token can appear in shell history and process listings.

hyp leave

hyp leave

Removes the central layer, identity, and forwarding credential, restarts the daemon, and reverses organization-driven client attaches. It keeps the local configuration, daemon service, query history, and recordings. Partial failure returns 1 and prints repair commands.

hyp leave

Manage the daemon

hyp daemon <subcommand> [args...]

Use hyp daemon --help to list service operations:

hyp daemon --help

Daemon commands don't activate plugins.

hyp daemon install

hyp daemon install [--config <path>] [--bin <path>] [--dry-run [--json]]

Installs the persistent launchd or systemd user service. When invoked from an ephemeral npx path, it installs a durable global package before it writes the service. --dry-run renders the exact service definition without changing the machine; add --json for structured plan output.

hyp daemon install --dry-run --json

hyp daemon uninstall

hyp daemon uninstall

Warning: This command stops persistent capture and detaches clients. Check hyp status before you uninstall the daemon so you know which clients it changes.

Removes the persistent service, then detaches every attached client so no client points at a dead gateway. It keeps configuration, recordings, and logs. The command doesn't ask for confirmation. If service removal succeeds but a detach fails, the command returns 1 and prints the detach command needed to finish.

hyp daemon uninstall

hyp daemon run

hyp daemon run [--config <path>]

Runs the daemon in the current terminal until it receives a stop signal. daemon start starts the installed service.

hyp daemon run

hyp daemon start

hyp daemon start

Starts the installed service. It returns 1 if no service is installed or the service manager can't start it.

hyp daemon start

hyp daemon status

hyp daemon status [--json]

Reads the daemon status and process ID files without activating plugins. A missing status file prints not started and returns 0. Malformed status or read failures return 1.

hyp daemon status --json

hyp daemon stop

hyp daemon stop

Signals the running daemon and waits up to five seconds. An already stopped daemon succeeds. A timeout returns 1.

hyp daemon stop

hyp daemon restart

hyp daemon restart [--processing]

Restarts an installed service. If no service is installed, it stops a foreground daemon and tells you how to relaunch or install it.

--processing replaces only the supervised processing daemon (recording, sinks, backfill and maintenance) and leaves the gateway listener, its sockets and its in-flight streams alone. It asks the running gateway to bounce its child and returns as soon as the request is written; the gateway allows the child four seconds to stop before killing it. With no gateway supervising a processing daemon it prints that and returns 1.

hyp daemon restart
hyp daemon restart --processing

Validate configuration

hyp config <subcommand> [args...]

Use hyp config --help to list configuration operations:

hyp config --help

hyp config validate

hyp config validate [file]

Loads the effective configuration or an explicit file and cross-validates plugin, dataset, source, and sink contracts. It is read-only. Validation failures return 1 with detailed pointers.

hyp config validate ./hypaware-config.json

Manage the local cache

hyp cache <subcommand> [args...]

Use hyp cache --help to list cache operations:

hyp cache --help

hyp cache status

hyp cache status

Prints dataset registration and cache freshness. It is read-only.

hyp cache status

hyp cache refresh

hyp cache refresh [dataset]

Forces refresh for one dataset or every registered dataset. It writes refreshed partitions to the local cache.

hyp cache refresh ai_gateway_messages

hyp cache maintain

hyp cache maintain [dataset] [--dry-run] [--force] [--compact-only] [--expire-only]

Runs legacy migration, snapshot expiration, compaction, and settlement work for one dataset or all datasets. --dry-run writes nothing. --compact-only and --expire-only limit the operation. Maintenance continues past partition failures and returns 1 if any partition failed.

hyp cache maintain ai_gateway_messages --dry-run

Maintain exports

hyp sink <subcommand> [args...]

Use hyp sink --help to list sink operations:

hyp sink --help

hyp sink maintain

hyp sink maintain [instance] [--compact] [--dry-run]

Expires table-format export snapshots for one sink instance or all eligible instances. Only --compact rewrites data files. --dry-run writes nothing.

hyp sink maintain local-parquet --dry-run

Manage plugins

hyp plugin <subcommand> [args...]

Use hyp plugin --help to list plugin operations:

hyp plugin --help

hyp plugin install

hyp plugin install <source> [--ref <ref>] [--path <subdir>] [--yes]

Installs a plugin from a recognized name, Git source, or local directory and updates the plugin lock. For remote code, HypAware fetches and validates the manifest, then shows the source, resolved revision, permissions, and warnings before confirmation. Non-interactive remote installation requires --yes. Pin a commit with --ref when the source has no fragment. --path is reserved but isn't currently supported for Git subdirectories.

hyp plugin install github:example/hypaware-plugin-widget --ref COMMIT_SHA

Replace COMMIT_SHA with a reviewed commit. Installing code authorizes it to run during plugin activation, so don't approve an unreviewed source.

hyp plugin list

hyp plugin list [--json]

Lists active bundled plugins and installed plugins with source and state.

hyp plugin list --json

hyp plugin info

hyp plugin info <plugin>

Prints version, source, and lock details for one installed plugin, including its update state when a check has run. An install under a name this package bundles also gets a shadowed: line: boot selects the bundled copy, so that install never runs, and the line names the hyp plugin remove that clears it. Answers for a bundled plugin too: those have no install record, so it prints the version and root directory from the manifest instead. A name that is neither installed nor bundled exits 1.

hyp plugin info @example/hypaware-plugin-widget
hyp plugin info @hypaware/claude

hyp plugin outdated

hyp plugin outdated [--json]

Lists installed plugins whose cached update metadata reports a newer revision. It doesn't install an update.

hyp plugin outdated --json

hyp plugin update

hyp plugin update [plugin] [--yes]

With a plugin name, fetches, validates, confirms, and installs that plugin's new revision. It applies the same remote-code trust gate as install. Without a plugin name, it refreshes update metadata and doesn't install code.

hyp plugin update @example/hypaware-plugin-widget

hyp plugin remove

hyp plugin remove <plugin>

Removes installed plugin code and its lock entry. It doesn't edit the active configuration, so validate or reconfigure afterward if the configuration still names the plugin.

hyp plugin remove @example/hypaware-plugin-widget

Manage remote query targets

hyp remote <subcommand> [args...]

Use hyp remote --help to list remote operations:

hyp remote --help

hyp remote add

hyp remote add <name> <url>

Registers a named Model Context Protocol (MCP) query target in local configuration. It doesn't authenticate.

hyp remote add team https://hyp.example.com/mcp

hyp remote login

hyp remote login <name> [--token-file <path>] [--no-forward] [--no-daemon]

Signs in through a browser by default, or reads a static token from --token-file or standard input. It stores the credential with mode 0600. The parser also accepts --org, --no-browser, and --host. Unless you set --no-forward, login can enroll this machine, provision forwarding, and install the daemon. --no-daemon provisions without installing the service.

hyp remote login team --no-forward

hyp remote mint

hyp remote mint [name] [--label <label>] [--expires-days <n>]

Mints a long-lived CI enrollment token from your logged-in session and prints it once, for pasting into CI secrets. It requires a session stored by hyp remote login. Omit name to mint against the default target. --label names the gateway the token is bound to, and --expires-days overrides the 365-day default. Every CI run that joins with the token shares that one gateway, and the token itself never rotates.

hyp remote mint team --label repo-ci --expires-days 90

The token is written to standard output on its own; the summary line, the warning, and the recipe go to standard error, so hyp remote mint > ci.token stores exactly the secret.

Use the printed token as the CI recipe's bootstrap credential. The recipe names the base URL, which is what hyp join expects, even when the target was registered with a /v1/mcp suffix, and feeds the token on standard input rather than as a positional argument, which would expose a long-lived shared secret to ps and to set -x traces on the runner:

# setup
printf '%s' "$HYP_CI_TOKEN" | hyp join https://hyp.example.com --no-daemon
hyp daemon run &
# ... the job's steps ...
# teardown: flush what the schedule has not exported yet
hyp sync --yes

hyp remote list

hyp remote list [--json]

Lists target URLs and credential status. It never prints credential values.

hyp remote list --json

hyp remote remove

hyp remote remove <name>

Removes the named target and its locally stored token. It doesn't leave HypAware Cloud enrollment; use hyp leave for that.

hyp remote remove team

Serve MCP tools

hyp mcp serve

hyp mcp serve [--remote <target> [--org <label|*>]]

Serves active typed verbs over standard input and output, or proxies a named remote target. Standard output is protocol-only. Human diagnostics go to standard error. The current release refuses an HTTP serving mode.

hyp mcp serve --remote team

Build and maintain the activity graph

Plugin: @hypaware/context-graph. Use graph help to list the active commands:

hyp graph <subcommand> [args...]

hyp graph --help

hyp graph project

hyp graph project [--source <dataset>] [--dry-run]

Reads registered projection contracts and writes the derived node and edge datasets. It is idempotent. --source limits projection to one source dataset, and --dry-run writes nothing. An empty successful result means that no eligible recordings exist.

hyp graph project --dry-run

hyp graph compact

hyp graph compact [--dry-run]

Merges duplicate graph rows and rewrites affected partitions in sorted order. Queries don't require compaction, but large graphs can read faster afterward.

hyp graph compact --dry-run

Inspect vector indexes

Plugin: @hypaware/vector-search.

hyp vector status

hyp vector status [--json]

Reports local vector-index configuration, shard coverage, and staleness. It is read-only and requires active vector-search and embedder capabilities.

hyp vector status --json

Enrich the activity graph

Plugin: @hypaware/context-graph-enrich. The visible hyp enrichment group lists its operations:

hyp enrichment <propose|curate|backfill|status>

hyp enrichment --help

Enrichment can call configured completion providers and write proposal, resolution, committed-knowledge, and derived graph data.

hyp enrichment propose

hyp enrichment propose

Runs one T1 proposal tick over settled sessions and writes new prospect rows.

hyp enrichment propose

hyp enrichment curate

hyp enrichment curate

Runs one synchronous T2 curation tick over pending prospects. It can call the configured completion provider and write resolution and committed rows.

hyp enrichment curate

hyp enrichment backfill

hyp enrichment backfill [--propose-only|--curate-only]

Processes historical sessions. The parser also accepts --since YYYY-MM-DD to scope curation and --dry-run to avoid submitting curation batches. --propose-only and --curate-only are mutually exclusive. Proposal work can write prospect rows before a later dry-run curation phase, so use --curate-only --dry-run when you require a completely read-only check of the curation pool.

hyp enrichment backfill --curate-only --since 2026-08-01 --dry-run

hyp enrichment status

hyp enrichment status

Prints proposal and curation watermarks plus prospect, resolution, and committed-knowledge counts. It is read-only.

hyp enrichment status

Update HypAware

hyp update

hyp update

Checks the npm registry and installs a newer HypAware release into a global installation, then restarts the installed daemon. It also repairs a daemon still running an older version than the package on disk. Foreground daemons need a separate relaunch; source checkouts and npx-cache copies do not self-update. Failures return 1 with a reason and repair guidance.

See updating and recovery.

Control optional product telemetry

hyp telemetry

hyp telemetry [status|preview|off|enable local|enable organization]

Product telemetry is automatic for enrolled organizations and defaults off on standalone installations. status reports consent, destination, and queue state; preview prints the next serialized batch or null. enable local retains an allowlisted preview queue without delivery. enable organization requires an eligible HypAware Cloud enrollment. off removes pending copies and stops collection, but cannot retract records already accepted remotely.

See product telemetry for daemon restart requirements, what is collected, and delivery limits.

hyp version

hyp version

Prints the HypAware version, Node.js version, platform, architecture, and effective HYP_HOME. It doesn't activate plugins.

hyp version

Develop plugins

hyp dev <subcommand> [args...]

Use hyp dev --help and hyp dev plugin --help to list developer commands:

hyp dev --help
hyp dev plugin --help

hyp dev plugin new

hyp dev plugin new <name> [--kind source|sink|dataset] [--dir <path>]

Creates a source, sink, or dataset plugin scaffold. It refuses to overwrite an existing target.

hyp dev plugin new @example/hypaware-plugin-widget --kind source --dir ./plugins

hyp dev plugin doctor

hyp dev plugin doctor [dir] [--json]

Aggregates static manifest and entrypoint checks, then imports and activates the plugin in an isolated state directory. This is a dry-run for state paths, not a security sandbox. Run it only on code you trust. Warnings can return 0; errors return 1.

hyp dev plugin doctor ./plugins/hypaware-plugin-widget --json

Talk to an engineer

Talk to Sales