# Query recorded data Canonical: https://hypaware.ai/docs/cli-reference/query-recorded-data ```text hyp query [args...] ``` Use `hyp query --help` to list the query subcommands available in the current configuration: ```sh 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 ` 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` ```text hyp query overview [--json] [--sql] [--days ] [--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. ```sh 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` ```text hyp query sql [--include-local-only] [--format ] [--output ] [--max-cell ] [--max-bytes ] [--remote [--org ]] ``` 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`. ```sh 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` ```text hyp query grep [--regex] [--session-id ] [--chain-id ] [--from ] [--to ] [--limit ] [--include-local-only] [--format ] [--output ] [--max-cell ] [--max-bytes ] [--remote [--org ]] ``` 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. ```sh 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` ```text hyp query schema ``` 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. ```sh hyp query schema ai_gateway_messages ``` ## `hyp query graph neighbors` Plugin: `@hypaware/context-graph`. ```text hyp query graph neighbors [--depth ] [--type ] [--edge-type ] [--direction out|in|both] [--limit ] [--include-local-only] [--format ] [--output ] [--max-cell ] [--max-bytes ] [--remote [--org ]] ``` 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. ```sh 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: ```text hyp query vector [args...] ``` ```sh 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: ```text hyp query vector search [--index ] [--dataset ] [--top-k ] [--no-refresh] [--format ] [--max-cell ] [--max-bytes ] ``` 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. ```sh hyp query vector search "daemon restart failure" --top-k 5 --format json ```