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"

A malformed flag or a missing statement returns a usage error. The statement itself is parsed during the run, so invalid or non-read-only SQL returns 1, as do query and output failures. A --remote failure splits on who refused: an unregistered target, no stored credential, or a stored login the identity endpoint reports as revoked or expired returns 2; a failure at the remote itself returns 1, whether a transport error, an error the remote reports, a credential it rejects, or an --org refusal.

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 @hypaware/grep, which standard capture setups enable. An explicit enabled: false entry keeps it disabled. An existing configuration gains the plugin automatically on startup; the migration backs the local config up before writing it. 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 is a usage error naming the maximum, not a quiet 1000, and so is a value the flag cannot use at all (0, negative, fractional) 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, and it doesn't open the dataset's source. A dataset that declares no columns (an S3 query source with no schema, for example) prints columns: none declared rather than a count: SQL still resolves the source's columns when a query runs, and the output names a query that shows them.

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/app.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.

hyp query vector search

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

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

hyp query vector --help

Requires active @hypaware/vector-search and a configured embedder provider, such as @hypaware/embedder-openai, plus at least one configured vector index.

Search syntax is:

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

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