CLI reference

Run hikyo for the exact help shipped by your binary. This page is a map, not a replacement for version-matched help.

Server and host operator

Command family	Purpose
`server`, `migrate`	Serve Hikyo and manage schema state.
`admin`	Bootstrap and break-glass account authority on the server host.
`backup`, `restore`	Export, reconstruct, inspect, and reconcile an instance.
`version`	Print readable build identity interactively; retain legacy one-line output when redirected.
`about`, `welcome`	Show Hikyo’s full terminal artwork and product information.

Authentication and local state

Command family	Purpose
`login`, `logout`, `whoami`	Manage the local human session.
`account`	Establish credentials, factors, recovery, and reset.
`context`	Store named targets and trusted instance references.
`doctor`	Report server-authoritative provider health.
`update`	Select `stable`, `nightly`, or `off`, check for a newer release, and install it after confirmation.

Passwords and authorities are read from the controlling terminal. Sessions are stored locally and are never printed as a login receipt.

Domain resources

Command family	Purpose
`org`, `project`, `env`	Manage hierarchy.
`folder`, `key`	Manage the catalogue and declarations.
`values`	List, get, set, clear, diff, copy, and bulk declare.
`access`, `project-settings`	Manage grants, members, and protected environments.
`adapter`	Configure Forgejo deployment adapters, targets, plans, adoption, and converge jobs.

Most list and show commands accept -o table|json. JSON shapes may gain fields; automation must ignore unknown fields.

adapter create atomically creates an adapter, its write-only credential, and its first target. Credential input is a no-echo terminal, --stdin, or --value-file; it is never accepted as an argument value.

hikyo adapter create --provider forgejo|github-actions --origin URL --env ENV --kind repository|organization|environment --owner OWNER [--repo REPO] [--destination-environment NAME] [--visibility all|private|selected] [--selected-repository-ids ID,ID] --prefix PREFIX --keys ID,ID [--stdin|--value-file FILE]
hikyo adapter update ADAPTER --origin URL [--keep-remote] [--stdin|--value-file FILE]
hikyo adapter update ADAPTER --target TARGET --env ENV --kind KIND --owner OWNER [--repo REPO] [--destination-environment NAME] [--visibility all|private|selected] [--selected-repository-ids ID,ID] --prefix PREFIX --keys ID,ID [--keep-remote]
hikyo adapter update ADAPTER --move MOVE --origin URL [--stdin|--value-file FILE]
hikyo adapter update ADAPTER --move MOVE --target TARGET --env ENV --kind KIND --owner OWNER [--repo REPO] [--destination-environment NAME] [--visibility all|private|selected] [--selected-repository-ids ID,ID] --prefix PREFIX --keys ID,ID
hikyo adapter update ADAPTER --move MOVE --cancel-move
hikyo adapter credential set --adapter ADAPTER [--stdin|--value-file FILE]
hikyo adapter credential set --adapter ADAPTER --move MOVE [--stdin|--value-file FILE]
hikyo adapter credential revoke --adapter ADAPTER
hikyo adapter target add --adapter ADAPTER --env ENV --kind KIND --owner OWNER [--repo REPO] [--destination-environment NAME] [--visibility all|private|selected] [--selected-repository-ids ID,ID] --keys ID,ID
hikyo adapter target list --adapter ADAPTER
hikyo adapter target show|remove TARGET
hikyo adapter plan|sync|test --target TARGET
hikyo adapter adopt --target TARGET [--artifact ARTIFACT] NAME...

A target update replaces the complete key subset. Target fields cannot be mixed with adapter-level origin or credential fields. The environment is immutable; repeat the current environment when updating, or remove and re-add the target to move it. Origin and destination changes return a durable asynchronous move; the table output includes its move id, state, pending route, jobs, and orphaned names. Adoption without --artifact succeeds only when exactly one eligible artifact matches every requested name exactly. See deployment adapters for custody, prefixing, scopes, and teardown behavior.

An attention_required move is always addressed explicitly with --move. Supplying the new route replaces its pending claims and resumes activation; credential set with --move replaces only that origin move’s pending credential. --cancel-move atomically restores the old route and queues its reconverge. These forms cannot mutate the live credential by ambiguity.

Commands that consume adapter authority bind an ephemeral loopback listener, open /reauth/cli?transaction=<opaque-state> in the browser, and wait for its exact callback. The browser displays the operation and complete environment set, collects one TOTP proof for all nonzero-window environments and one passkey proof for each zero-window environment, then returns only a single-use code and the same state. PKCE binds redemption to the waiting process. The rotated session bearer is written silently to local mode-0600 state and is never printed, logged, or placed in the browser URL.

Identity providers and machines

Command family	Purpose
`sa`	Service accounts, credentials, and federation bindings.
`instance-config`	SAML, federation issuers, credential policy, and instance keys.
`scim`	Provisioning bindings, mappings, credentials, users, and groups.

Display-once values use one of three destinations: a new mode-0600 file, an interactive terminal, or explicit --dangerously-print.

Target flags

The shared dimensions are --instance, --org, --project, --env, and --context. Resolution is documented in contexts and targets.

Workload delivery

run and compose accept machine credentials only, through --token-file or HIKYO_TOKEN. compose has no human path. run has one narrow exception: --use-human-session runs under the stored human session, but only when all of a controlling terminal with stderr on it, an enumerated confirmation of the environment and key set, and a live disclosure window hold. Without a live window the CLI opens one: an authenticator code at the terminal where the environment’s window allows it, otherwise a browser handoff to the passkey ceremony over the keys it will inject. The four conditions hold under --config-only too.

hikyo run [--config-only] [--allow-override KEY,KEY] [--project-directory DIR] [--token-file PATH] -- <command> [args...]
hikyo run --use-human-session [--config-only] -- <command> [args...]
hikyo compose render [--project-directory DIR] [--config-only] [--token-file PATH]
hikyo compose sync [--project-directory DIR] [--token-file PATH]
hikyo compose doctor [--project-directory DIR] [-o table|json] [--token-file PATH]

run fetches, merges, checks the composite ARG_MAX, and replaces itself with the command. Fetched values win; a differing inherited value is refused unless its key is named in --allow-override. Command-not-found exits 127 and a found but non-executable command exits 126.

values export writes a whole environment. --format selects the payload: table (default), json, or dotenv. The dotenv encoding matches the Compose renderer’s. Secrets appear only under --reveal; without it they are omitted and counted on stderr, and with it the output obeys the print triad.

compose render atomically writes raw-dotenv generations and the managed .env stamp block. compose sync renders conditionally and runs docker compose up -d only when a stamp moved. compose doctor checks the 2.30.0 floor and config/stamp/generation/server agreement; findings go to stdout and an error exits 4. See Docker Compose delivery.

Exit codes

Code	Meaning	Typical response
`0`	Success	Continue.
`1`	Internal failure	Preserve error and server logs.
`2`	Usage error	Correct verb, arguments, or flags.
`3`	Authentication failure	Log in or replace credential.
`4`	Refused	Satisfy the named safety or policy condition.
`5`	Not found or unauthorized	Check target and authorization.
`6`	Unavailable	Retry only after checking service health.

Code 5 deliberately combines missing and unauthorized resources.

Import and migration

import supports Kubernetes, SOPS, Vault/OpenBao, and Infisical files plus live Kubernetes and Vault/OpenBao sources. Use explicit flag mode or replay a recorded mapping; run hikyo import --help for the current source-specific flags.

The interactive, multi-environment wizard is not implemented yet. Running hikyo import without --from or --mapping refuses explicitly and directs you to the available modes. Completion is tracked by #112.

For a plaintext .env, use definitions scaffold --from .env to author a declaration offline, then values import --from-dotenv .env for the values. See value workflows.

Definitions

definitions manages the reviewable, Git-friendly catalogue.

hikyo definitions scaffold --from <.env>
hikyo definitions export [--portable] [--output-file PATH]
hikyo definitions check --file PATH [-o table|json]
hikyo definitions plan --file PATH [-o table|json]
hikyo definitions apply --plan ID [--file PATH] [--allow-delete]

scaffold is a pure offline transform: it reads only the named .env, contacts no server, and emits an additive bundle every key of which is config with a TODO: classify marker. check exits 0 equal, 1 different, 2 on error.

Commands not yet implemented

render, sync, and adopt remain reserved top-level stubs. Compose delivery uses compose render and compose sync; adopt is not implemented in the current 0.x build.