hiloop CLI is a thin REST/JSON client over the hiloop API. Install
it and authenticate per the quickstart, then use the commands below.
hiloop
The hiloop control-plane CLI
Usage: hiloop [OPTIONS] <COMMAND>
Commands:
whoami Print the identity the API resolves for your credential (`GET /v1/whoami`)
projects Manage the projects in your org (`ProjectService`)
runs Orient in logical run lineage (`RunService`): list runs, show one run's event transcript, and record a run's terminal status
events Read captured events: fetch an event's raw payload bytes, exactly as captured
sandbox Create, inspect, connect to, persist, and delete sandboxes
volume Publish and manage versioned data mounted by sandboxes
keys Manage your API keys (`/keys`)
skills Install the hiloop Agent Skills bundle for an AI coding harness. Re-running the command safely refreshes an existing installation
workloads Manage your org's registered workloads (`/v1/workloads`): named machine identities a run can be launched as. Attribution renders the workload's name, and each workload carries a launch ACL saying who may launch as it
workload-identity Use a sandbox's ambient workload identity with cloud SDKs. Tokens are minted on demand; no refresher daemon or default AWS/Google token file is created. Sandboxes cannot yet be launched as a workload, so these subcommands have no ambient identity to mint against
secret Manage org-scoped, write-only sandbox credentials. Values are stored encrypted and never returned. Deployments without proof-bound release refuse sandbox bindings
query Run a read-only SQL query over your captured events. The pragmatic flags build a `SELECT` for the common case; `--sql` sends an arbitrary `SELECT` for full control — over events, payload joins, and every registered view (including the `ann_<schema>` annotation views; the view name lowercases the schema name and turns every non-alphanumeric character into `_`, so schema `kaggle.submission.v1` is queried as `ann_kaggle_submission_v1` — `data-views list` shows the exact names). Your identity scopes the query, so the SQL itself is org-agnostic
usage Show your org's configured limits and current usage (`GET /v1/usage/snapshot`)
data-views Manage data views (`TelemetryViewService`): named SQL views you can query like tables. A view stores an org-agnostic `SELECT`; your identity scopes every run, and the SQL is re-validated on each execution. Create one and read it back with `hiloop query --sql "SELECT … FROM <name> …"`
annotations Add and read annotations: durable, structured judgments you can filter and aggregate later. Attach one to a run, an event or time window within it, or a project; list the current value per (anchor, schema, target), refined by schema identity fields, or every stored version
annotation-schema Manage your annotation schemas — the named, versioned JSON-Schema configs that ingest validates annotation payloads against (`AnnotationSchemaService`)
feedback Send a bug report or product feedback to the hiloop team (`POST /v1/feedback`). The report is stored under your org and surfaced to the team for review. A quick one-liner is enough; the structured bug fields (`--severity`, `--expected`/`--actual`, `--repro`) and telemetry correlation (`--evidence`) make a report actionable. Your CLI version is attached automatically
config Manage CLI configuration
api Make an authenticated request to an arbitrary API path (gh-style passthrough). Covers the whole REST surface. A JSON or text response body is pretty-printed; a binary response (e.g. an artifact payload) is written to stdout byte-identical — refused with a hint when stdout is a terminal, so raw bytes never scramble an interactive session
run Wrap an agent command and stream its telemetry to the hiloop gateway. Everything after `--` is the command to run, e.g. `hiloop run -- claude "fix the bug"`. The child's exit code is propagated, so `hiloop run` is transparent in scripts
login Sign in. By default this opens your browser to approve the login, then caches a refreshable session for future commands. On a headless or remote host, use `--device` to approve from another device, or `--with-key` to store a dashboard API key read from stdin. A piped stdin (`echo "$KEY" | hiloop login`) takes the API-key path automatically
logout Sign out — remove the cached session and any stored API key for the selected context
upgrade Update hiloop to the latest released version, in place. Downloads and installs the newest build from the official release channel; prints `current → new`, or reports that you're already up to date. Only works for installer-based installs (`curl | sh`) — a source or package-manager install is told how to update instead [alias: update]
completions Print a shell completion script to stdout. Source it (or install it where your shell looks) to get tab-completion for commands, flags, and values, e.g. `hiloop completions zsh > ~/.zfunc/_hiloop`
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
Coding agents: hiloop skills install <harness> · https://docs.hiloop.ai/guides/for-agents
hiloop annotation-schema
Manage your annotation schemas — the named, versioned JSON-Schema configs that ingest validates annotation payloads against (`AnnotationSchemaService`)
Usage: hiloop annotation-schema [OPTIONS] <COMMAND>
Commands:
register Register a schema in your org (`POST /v1/annotation-schemas`). Schema names are shared across the whole org, so namespace them per workstream (`kaggle.submission.v1`, not `submission.v1`) — re-registering a name someone else already uses silently creates its next version. An unseen name starts at version 1; an existing name creates the next version after a backward-compatibility check. Registration also creates the schema-named query views `ann_<schema>` (current versions) and `ann_<schema>_history` (every stored version), where the schema name is lowercased and every non-alphanumeric character (dots included) becomes `_` — registering `kaggle.submission.v1` makes its annotations queryable as `ann_kaggle_submission_v1`
list List the schemas in your org (`GET /v1/annotation-schemas`). By default the latest live version per name
get Get a schema by name (`GET /v1/annotation-schemas/{name}`) — the latest live version, or a specific `--version`
archive Archive a schema version (`POST /v1/annotation-schemas/{name}:archive`) — retire it without deleting it. Existing annotations stay valid against the version stamped on them
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop annotations
Add and read annotations: durable, structured judgments you can filter and aggregate later. Attach one to a run, an event or time window within it, or a project; list the current value per (anchor, schema, target), refined by schema identity fields, or every stored version
Usage: hiloop annotations [OPTIONS] <COMMAND>
Commands:
add Add an annotation to a run, an event or time window within it, or a project. The payload is validated against the registered schema and sent through the telemetry ingest path
list List a target's annotations (`GET /v1/telemetry/annotations`): a run's own, or a project's run-less annotations
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop api
Make an authenticated request to an arbitrary API path (gh-style passthrough). Covers the whole REST surface. A JSON or text response body is pretty-printed; a binary response (e.g. an artifact payload) is written to stdout byte-identical — refused with a hint when stdout is a terminal, so raw bytes never scramble an interactive session
Usage: hiloop api [OPTIONS] <PATH>
Arguments:
<PATH>
API path, e.g. `/v1/whoami`
Options:
--api-url <API_URL>
Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet
[env: HILOOP_API_URL=]
-X, --method <METHOD>
HTTP method (any casing)
Possible values:
- get: `GET`
- post: `POST`
- put: `PUT`
- patch: `PATCH`
- delete: `DELETE`
[default: get]
--context <CONTEXT>
Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context
[env: HILOOP_CONTEXT=]
-d, --data <DATA>
Request body. Inline (`'{"k":1}'`) or `@file` to read from a file. Text is sent as `application/json`; a non-text (binary) file is sent byte-identical as `application/octet-stream`. Override either with `-H 'Content-Type: <type>'`
--api-key <API_KEY>
API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used
[env: HILOOP_API_KEY]
-H, --header <HEADER>
Extra request header `Name: Value` (repeatable)
--output <OUTPUT>
Output format. Only `json` is supported for the generic passthrough — there is no schema to render an arbitrary response body as a table
[default: json]
[possible values: table, json]
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
hiloop completions
Print a shell completion script to stdout. Source it (or install it where your shell looks) to get tab-completion for commands, flags, and values, e.g. `hiloop completions zsh > ~/.zfunc/_hiloop`
Usage: hiloop completions [OPTIONS] <SHELL>
Arguments:
<SHELL> Shell to generate completions for [possible values: bash, elvish, fish, powershell, zsh]
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop config
Manage CLI configuration
Usage: hiloop config [OPTIONS] <COMMAND>
Commands:
get-contexts List configured contexts
current-context Print the effective context for this invocation
use-context Make a context active for future invocations
set-context Create or update a context
remove-context Delete a context
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop data-views
Manage data views (`TelemetryViewService`): named SQL views you can query like tables. A view stores an org-agnostic `SELECT`; your identity scopes every run, and the SQL is re-validated on each execution. Create one and read it back with `hiloop query --sql "SELECT … FROM <name> …"`
Usage: hiloop data-views [OPTIONS] <COMMAND>
Commands:
create Create or replace a named SQL data view (`PUT /v1/telemetry/data-views/{name}`). The SQL is validated before it is stored; querying the view later re-validates it again
list List your data views (`GET /v1/telemetry/data-views`)
delete Delete a data view (`DELETE /v1/telemetry/data-views/{name}`). Deleting a name you don't have a view under is an error, not a silent no-op
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop events
Read captured events: fetch an event's raw payload bytes, exactly as captured
Usage: hiloop events [OPTIONS] <COMMAND>
Commands:
payload Print an event's raw captured payload to stdout, byte-exact (`GET /v1/telemetry/events/{event_id}/payloads/{digest}` via the event's payload reference). Bodies are stored content-addressed, so what you get is exactly what crossed the boundary — pipe it to a file or a JSON tool
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop feedback
Send a bug report or product feedback to the hiloop team (`POST /v1/feedback`). The report is stored under your org and surfaced to the team for review. A quick one-liner is enough; the structured bug fields (`--severity`, `--expected`/`--actual`, `--repro`) and telemetry correlation (`--evidence`) make a report actionable. Your CLI version is attached automatically
Usage: hiloop feedback [OPTIONS] <TITLE>
Arguments:
<TITLE> A short summary of the report (at most 300 characters)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--surface <SURFACE> The product surface the report is about (any casing) [default: cli] [possible values: cli, api, web, sandbox, telemetry, annotations, docs, other]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--severity <SEVERITY> How severe the problem is (any casing). Omit for general feedback that is not a bug [possible values: critical, high, medium, low]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-m, --message <MESSAGE> Free-form feedback text
--expected <EXPECTED> What you expected to happen
--actual <ACTUAL> What actually happened
--repro <REPRO> Steps to reproduce the problem
--evidence <ID> A run, event, or artifact id linking the report to recorded telemetry. Repeatable
--fingerprint <FINGERPRINT> A stable deduplication key (for example `cli/tail-resize-panic`) so repeat reports of the same finding are grouped together
--output <OUTPUT> Output format [default: table] [possible values: table, json]
-h, --help Print help
-V, --version Print version
hiloop keys
Manage your API keys (`/keys`)
Usage: hiloop keys [OPTIONS] <COMMAND>
Commands:
list List your API keys — metadata only, never the secret (`GET /keys`)
create Mint an API key; the plaintext secret is shown once and never again (`POST /keys`)
revoke Revoke a key by id or name; idempotent (`DELETE /keys/{id}`)
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop login
Sign in. By default this opens your browser to approve the login, then caches a refreshable session for future commands. On a headless or remote host, use `--device` to approve from another device, or `--with-key` to store a dashboard API key read from stdin. A piped stdin (`echo "$KEY" | hiloop login`) takes the API-key path automatically
Usage: hiloop login [OPTIONS]
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--device Approve the login from another device instead of this one — prints a URL and a short code to enter there. Use this on a headless or remote host with no local browser
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--with-key Store a dashboard API key (read from stdin, one line) instead of running a browser flow. The key is verified against `GET /v1/whoami` before it is stored
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop logout
Sign out — remove the cached session and any stored API key for the selected context
Usage: hiloop logout [OPTIONS]
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop projects
Manage the projects in your org (`ProjectService`)
Usage: hiloop projects [OPTIONS] <COMMAND>
Commands:
list List the projects in your org, newest first (`GET /v1/projects`)
create Create a project in your org (`POST /v1/projects`)
get Get a project by id or slug (`GET /v1/projects/{id}`)
set Update a project's name or description (`PATCH /v1/projects/{id}`). Only the flags you pass change; the slug is immutable
delete Delete a project (`DELETE /v1/projects/{id}`). By default only a project with no resources deletes — one that still has runs, sandboxes, or other resources is a conflict. Pass `--cascade` to delete its dependent records; a cascade never tears down a live sandbox (delete the project's sandboxes first). Asks for confirmation unless `--yes`
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop query
Run a read-only SQL query over your captured events. The pragmatic flags build a `SELECT` for the common case; `--sql` sends an arbitrary `SELECT` for full control — over events, payload joins, and every registered view (including the `ann_<schema>` annotation views; the view name lowercases the schema name and turns every non-alphanumeric character into `_`, so schema `kaggle.submission.v1` is queried as `ann_kaggle_submission_v1` — `data-views list` shows the exact names). Your identity scopes the query, so the SQL itself is org-agnostic
Usage: hiloop query [OPTIONS]
Options:
--api-url <API_URL>
Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--run-id <RUN_ID>
The run (session) to query. Required unless `--sql` is given
--context <CONTEXT>
Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--signal <SIGNAL>
Restrict to one signal (e.g. `llm`)
--api-key <API_KEY>
API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
--fields <FIELDS>
Columns to return, comma-separated (plain column names), or `*` for every column. Omitted selects a minimal default set (event id, time, signal, name, run identity, principal, payload size); use `--sql` for expressions or joins
--limit <LIMIT>
Row cap; omitted returns all matching rows
--since <SINCE>
Inclusive window start — RFC 3339 (`2026-06-25T00:00:00Z`) or nanoseconds
--until <UNTIL>
Inclusive window end — RFC 3339 or nanoseconds
--sql <SQL>
Run an arbitrary read-only `SELECT` verbatim. `@file` reads a file, `-` (or `@-`) reads stdin, anything else is inline SQL. Mutually exclusive with the pragmatic flags
--project <PROJECT>
Project scope for the query (slug or id): `--project` > `HILOOP_PROJECT` > the context's project. When set, annotation rows (`ann_*` views and the `annotation` signal) are read from that project only — run-scoped and project-scoped alike. Project-scoped annotations (written with `annotations add --project`) are readable only for a selected project — this scope, or a `project_id = '<id>'` filter written directly in the SQL; without either the query spans your org's run-scoped data and returns no project-scoped annotations [env: HILOOP_PROJECT=]
--max-cell-width <MAX_CELL_WIDTH>
Max characters per table cell before truncation with `…` (0 disables truncation). Only affects `--output table`; `--output json` is always full [default: 48]
--output <OUTPUT>
Output format [default: table] [possible values: table, json]
-h, --help
Print help
-V, --version
Print version
hiloop run
Wrap an agent command and stream its telemetry to the hiloop gateway. Everything after `--` is the command to run, e.g. `hiloop run -- claude "fix the bug"`. The child's exit code is propagated, so `hiloop run` is transparent in scripts
Usage: hiloop run [OPTIONS] -- <COMMAND>...
Arguments:
<COMMAND>... The command to wrap; everything after `--` is passed to the child
Options:
--api-url <API_URL>
Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--endpoint <ENDPOINT>
Telemetry gateway gRPC endpoint override, e.g. `https://telemetry.example.com:443`. When omitted, the active API context's discovery document supplies it [env: HILOOP_TELEMETRY_ENDPOINT=]
--context <CONTEXT>
Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--insecure
Use cleartext h2c instead of TLS for the gateway connection (local dev gateways only)
--api-key <API_KEY>
API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
--project <PROJECT>
Project (slug or id) to record captured events under. Selection precedence is `--project` > `HILOOP_PROJECT` > the context's project > error [env: HILOOP_PROJECT=]
--label <LABEL>
A human-readable label for the run, shown by `hiloop runs list`. When omitted, one is assigned at registration
--as <workload/NAME>
Declare the executing identity as a registered workload, e.g. `--as workload/codex-runner`. The run is then attributed to that workload (you must hold launch rights on it, and the workload must be registered with `hiloop workloads create`). Omit to run as your own identity — the executing identity is always declared, never inferred from the command
--net-capture <NET_CAPTURE>
Network capture transport. `auto` uses transparent Linux capture when its preflight passes and otherwise warns before using the observation-only cooperative proxy. Restrictive egress policy requires `auto`/`netns` with a successful netns preflight [default: auto]
--no-otlp
Disable the embedded OTLP receiver (capture of the harness's own OpenTelemetry spans). On by default
--no-redact
Store non-OAuth captured bodies and allowlisted environment values without generic credential-pattern redaction. Exact supported OAuth token exchanges remain metadata-only
--export-batch-size <EXPORT_BATCH_SIZE>
Ship a partial batch of captured events once this many accumulate (the size trigger) [env: HILOOP_EXPORT_BATCH_SIZE=] [default: 128]
--export-flush-interval-ms <EXPORT_FLUSH_INTERVAL_MS>
Ship a partial batch after it has waited this many milliseconds, even before it reaches `--export-batch-size` (the age trigger). Lower it for a snappier `hiloop runs tail` on a long-running command; set to 0 to flush only on a full batch or when the command exits [env: HILOOP_EXPORT_FLUSH_INTERVAL_MS=] [default: 1000]
--verbose
Print wrapper diagnostics to stderr
--env-allowlist <NAMES>
Environment variables to record on the run's `process.start` event, comma-separated names (e.g. `PATH,PYTHONPATH,LEARNING_RATE`). The names are recorded as `process.env_allowlist`; each listed variable set for the run is also captured as a `process.env.<NAME>` attribute, scrubbed by the capture-side credential redaction unless `--no-redact` is set. Variables not listed are never captured [env: HILOOP_ENV_ALLOWLIST=]
--sample-resources
Record best-effort resource samples every 15 s as `resource.sample` events labeled `resource.source: "process_tree"`. Measures the whole run process tree — this wrapper plus the wrapped command's descendants — so it is most meaningful for commands that outlive a sampling interval. Off by default. Inside a hiloop sandbox the platform records authoritative host-side samples instead
--egress-deny
Deny all outbound network access by default, permitting only the destinations named by `--allow-domain` / `--allow-cidr`. Without this flag, all outbound traffic is allowed except the destinations named by `--deny-domain` / `--deny-cidr`
--allow-domain <DOMAIN>
The deny-mode allowlist: a destination domain to permit (suffix-matched). Repeatable. Requires `--egress-deny`; pairing it with the default allow mode is rejected
--allow-cidr <CIDR>
The deny-mode allowlist: a destination IP range (CIDR) to permit. Repeatable. Requires `--egress-deny`; pairing it with the default allow mode is rejected
--deny-domain <DOMAIN>
The allow-mode denylist: a destination domain to block (suffix-matched). Repeatable. Not valid with `--egress-deny`; that combination is rejected
--deny-cidr <CIDR>
The allow-mode denylist: a destination IP range (CIDR) to block. Repeatable. Not valid with `--egress-deny`; that combination is rejected
-h, --help
Print help
-V, --version
Print version
hiloop runs
Orient in logical run lineage (`RunService`): list runs, show one run's event transcript, and record a run's terminal status
Usage: hiloop runs [OPTIONS] <COMMAND>
Commands:
list List the runs in your org, one line per run — the scan altitude (`GET /v1/runs`). The table leads with in-flight runs (running, then pending), then the most recent of the rest; pass `--all` for the plain newest-first scan, and narrow with `--status`, `--since`, `--label`, `--principal`, `--project`, or `--root-run-id`
show Show one run's event transcript: every captured boundary (LLM turns, stdio, exec, annotations) in time order, with small payload contents resolved inline. `--output json` prints `{run, events}` — the run record plus the canonical event stream, payloads up to 64 KiB inlined under `payload_ref.inline`
tail Follow a run's telemetry live as events arrive (`GET /v1/telemetry/tail`). The streaming companion to `runs show`: one line per event, reconnecting automatically (resuming where it left off) without a fixed attempt limit until you stop it with Ctrl-C. Pass `--no-auto-resume` to use only the initial connection
complete Record a run's terminal status (`POST /v1/runs/{id}:complete`): stamp it succeeded, failed, or canceled and set its end time. Run lifecycle is client-owned — whatever starts a run ends it, or the run reads as live forever. Only a pending or running run can be completed; a run already in a terminal status refuses with `run_already_completed`
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop sandbox
Create, inspect, connect to, persist, and delete sandboxes
Usage: hiloop sandbox [OPTIONS] <COMMAND>
Commands:
create Create from an OCI image, a snapshot, or the platform default image, and wait until running. Pass a long-running command after `--` for an image whose own entrypoint exits
list List sandboxes in the active project
get Show one sandbox by name or id
grow Grow a durable workspace. Shrinking is not supported
update Update mutable sandbox settings
ssh Connect with stock OpenSSH, optionally running a command
cp Copy files or directories between this machine and a running sandbox
exec Run one buffered command through the sandbox agent
snapshot Create, list, or delete immutable snapshots
stop Seal and stop a sandbox
start Start a stopped sandbox, or return an already-running sandbox unchanged
delete Permanently delete a sandbox and wait for termination
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop secret
Manage org-scoped, write-only sandbox credentials. Values are stored encrypted and never returned. Deployments without proof-bound release refuse sandbox bindings
Usage: hiloop secret [OPTIONS] <COMMAND>
Commands:
set Store a new sandbox secret. The value is write-only and accepted only on piped stdin, keeping it out of argv and process listings. A deployment admits bindings only when its proof-bound release path is configured
list List your sandbox secrets — metadata only, never the value (`GET /v1/secrets`)
rotate Rotate a secret to a new value, stored as a new version. The value is write-only and accepted only on stdin
revoke Revoke a secret by name. A revoked secret cannot be delivered (`DELETE /v1/secrets/{id}`)
grant Grant one exact principal use of a secret. Repeating the same grant is safe
grants List the exact principals allowed to use a secret
ungrant Remove one principal's exact use grant. Repeating the removal is safe
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop skills
Install the hiloop Agent Skills bundle for an AI coding harness. Re-running the command safely refreshes an existing installation
Usage: hiloop skills [OPTIONS] <COMMAND>
Commands:
install Install or refresh the verified hiloop skills bundle for one harness or every supported harness
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop upgrade
Update hiloop to the latest released version, in place. Downloads and installs the newest build from the official release channel; prints `current → new`, or reports that you're already up to date. Only works for installer-based installs (`curl | sh`) — a source or package-manager install is told how to update instead
Usage: hiloop upgrade [OPTIONS]
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--check Check whether a newer version exists and report it, without installing anything
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--force Reinstall the latest version even if it's already installed (a repair path)
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop usage
Show your org's configured limits and current usage (`GET /v1/usage/snapshot`)
Usage: hiloop usage [OPTIONS]
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--output <OUTPUT> Output format [default: table] [possible values: table, json]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop volume
Publish and manage versioned data mounted by sandboxes
Usage: hiloop volume [OPTIONS] <COMMAND>
Commands:
create Create an empty project-scoped volume
push Publish a local directory as a new immutable version
list List volumes
get Show one volume by name or id
delete Permanently delete a volume and its versions
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop whoami
Print the identity the API resolves for your credential (`GET /v1/whoami`)
Usage: hiloop whoami [OPTIONS]
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--output <OUTPUT> Output format [default: table] [possible values: table, json]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop workload-identity
Use a sandbox's ambient workload identity with cloud SDKs. Tokens are minted on demand; no refresher daemon or default AWS/Google token file is created. Sandboxes cannot yet be launched as a workload, so these subcommands have no ambient identity to mint against
Usage: hiloop workload-identity [OPTIONS] <COMMAND>
Commands:
token Mint one short-lived federation JWT and write only that token to stdout
aws-credentials Emit AWS `credential_process` version-1 JSON after an in-process web-identity exchange
gcp-credential-source Emit Google Cloud's executable-sourced subject-token JSON envelope
azure-token-file Refresh the Microsoft Entra SDK fallback token file on boot-local tmpfs
setup Print cloud SDK wiring from this workload's registered federation descriptors
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version
hiloop workloads
Manage your org's registered workloads (`/v1/workloads`): named machine identities a run can be launched as. Attribution renders the workload's name, and each workload carries a launch ACL saying who may launch as it
Usage: hiloop workloads [OPTIONS] <COMMAND>
Commands:
create Register a workload in your org (`POST /v1/workloads`). Registration is always explicit — launching as an unregistered name is an error, never an implicit registration. A new workload starts open to launch by any org member
list List your org's registered workloads (`GET /v1/workloads`)
show Show one registered workload, including who may launch as it (`GET /v1/workloads/{name}`)
delete Delete a registered workload (`DELETE /v1/workloads/{name}`); idempotent — deleting a name that is not registered succeeds. Requires an owner or admin in the org. A workload whose sandboxes are still running is a conflict — stop them first. Past runs keep the workload's raw id in their attribution; once the name is gone that id does not resolve to a name, so prefer keeping workloads with meaningful history. Asks for confirmation unless `--yes`
allow-launch Set who may launch as a workload (`PUT /v1/workloads/{name}/launch-acl`). Requires an owner or admin in the org. Pass `--all-members` to open launching to every org member (the default for a new workload), or restrict launching to named principals by repeating `--user` and/or `--service-account`
federation Manage cloud workload-identity federation registrations and print org-pinned setup
help Print this message or the help of the given subcommand(s)
Options:
--api-url <API_URL> Base URL of the hiloop API. Set it (or save a context with `hiloop config set-context`) to point at your deployment; the hosted default edge is not live yet [env: HILOOP_API_URL=]
--context <CONTEXT> Named environment context to use for this invocation. Defaults to the active saved context, then the built-in prod context [env: HILOOP_CONTEXT=]
--api-key <API_KEY> API key used as the bearer credential, shared by the API CLI and the telemetry interceptor. When neither this flag nor `HILOOP_API_KEY` is set, the credential cached by `hiloop login` is used [env: HILOOP_API_KEY]
-h, --help Print help
-V, --version Print version