hanectl

This page explains hanectl, the CLI for definitions and projects. hanectl calls the public API and validates manifests with the same checks as the Hane server. Run hanectl --help to list every command.

Install

hanectl is distributed as a single executable and does not need Node.js.

File	Runs on
hanectl-darwin-arm64	macOS on Apple Silicon
hanectl-darwin-x64	macOS on Intel
hanectl-linux-arm64	Linux on arm64 (glibc)
hanectl-linux-x64	Linux on x64 (glibc). On Windows, use WSL2

shasum -a 256 -c SHA256SUMS --ignore-missing
install -m 755 hanectl-darwin-arm64 ~/.local/bin/hanectl
hanectl version

Caution

The macOS executables are not notarized. Gatekeeper may block them if you download them in a browser. They do not run on musl-based Linux such as Alpine.

Login and contexts

hanectl stores each combination of organization, project, and environment as a context in ~/.config/hanectl/config.json. Set the HANECTL_CONFIG environment variable to use a different file.

# with a service account API key (for CI, for example)
hanectl login --api-key "$HANE_API_KEY" --org acme --project fleet --env dev --server https://<gateway URL>

# with an id_token issued by your IdP (HANECTL_ID_TOKEN also works)
hanectl login --id-token "$ID_TOKEN" --org acme --project fleet --env dev --server https://<gateway URL>

hanectl config get-contexts
hanectl config use-context acme/fleet/prod
hanectl token        # print the access token of the current context (for scripts)

• An access token obtained with an id_token expires after 15 minutes. Log in again when it does.
• Every command accepts --context <name> to use a context other than the current one.
• When automation calls an environment that has Cloudflare Access in front of the gateway, pass HANE_ACCESS_CLIENT_ID and HANE_ACCESS_CLIENT_SECRET (an Access service token) as environment variables.

Load definitions

Command	What it does
hanectl validate -f <dir>	Checks shape and references locally (no login needed)
hanectl diff -f <dir> [--prune] [-o json]	Shows what apply would change
hanectl apply -f <dir> [--prune]	Saves drafts. Settings take effect at this point
hanectl get <kind> [name] [-o yaml|json]	Shows drafts
hanectl get --at <time>	Shows the active ReleaseBundle and settings at a point in time

With --prune, definitions that are not in the directory are marked as deprecated. In diff output, + means added, ~ changed, - deprecated, and ! a change that widens what is allowed.

apply records the repository, commit, and path as the source. If there are uncommitted changes or HEAD has not been pushed, it does not record the commit and prints a warning.

Create and activate a ReleaseBundle

hanectl release create -f definitions/bundle.yaml --activate
hanectl release list
hanectl release show <release_id>
hanectl release activate <release_id>

Promote to stage and prod

Copy a ReleaseBundle verified in dev to another environment’s context. Activating in stage and prod requires every evaluation (EvalSuite) for that version to pass.

hanectl release promote <release_id> --to acme/fleet/stage

• Activation, rollback, and canaries in prod are done by a person with their own login. A ReleaseBundle that a CI API key tries to activate stays pending and waits for a person.
• A ReleaseBundle that widens what AI may approve, or that gives an agent a new external action tool in stage or prod, cannot be activated until someone other than its creator reviews it with hanectl release review <id> --comment <reason>.
• Names that differ per environment (Connections, sender identities, secrets) go into an EnvironmentBinding, applied in that environment’s context.

Try on some new cases

hanectl release canary <release_id> --percent 10
hanectl release canary promote   # activate it
hanectl release canary abort     # stop

Check status and roll back

hanectl rollout status     # the active ReleaseBundle and anything waiting for a person
hanectl rollout history
hanectl rollout undo       # go back to the previous ReleaseBundle
hanectl rollout undo <kind> <name>   # return a setting to its previous revision

A ReleaseBundle that includes Migrations (renaming fields or changing their types) can run a backfill before activation. Rolling back stops at a Migration that cannot be reversed.

hanectl migrate status <release_id>
hanectl migrate backfill <release_id>

Sync from Git

One ReleaseBundle is created per commit. The same commit is never released twice.

hanectl git sync . --ref main --path definitions --activate
hanectl git hook install . --path definitions   # sync after each commit and merge

To have Hane pull from Git instead, register a GitSource with apply. In a project with a GitSource, apply is refused and Git is the only input (hanectl git source list|show|sync|pause|resume|delete|webhook).

Other commands

Command	What it does
hanectl import <Type> -f <file.csv> [--state estimated] [--label <name>]	Imports a CSV
hanectl schedules list, trigger <name>	Lists schedules, or triggers one with today’s date
hanectl runs list [--agent <name>] [--case <id>], show <id>, cancel <id>	Inspects or cancels AgentRuns
hanectl documents facts, stats, eval ...	Extracted facts, review stats, eval sets
hanectl ontology resolve, query, actions	Follows ontology terms and relations
hanectl subscriptions list, deliveries <id>, resume <id>	Reads event subscriptions and webhook deliveries, resumes a subscription
hanectl app create, deploy, build, image ...	Builds apps served by Hane (preview)

Many commands print JSON with -o json. On failure they exit with code 1, so you can use them in CI as is.

Next steps

Writing manifestsDefinition kinds and how to write them

Definitions and releasesDrafts, ReleaseBundles, promotion