CLI reference

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

Getting helpCopy Anchor Link

Every command answers --help (or -h) at any depth with exit 0, before it touches configuration, the datastore, the network, or the terminal. hikyo help <command...> is the same request spelled as a word. Help goes to stdout, except that server, migrate, and config-rollout print their flag parser’s usage on stderr.

hikyo --help                     every role of the binary, and the client verb list
hikyo help client                the full client reference
hikyo values --help              one verb family
hikyo adapter target --help      one sub-family, at any depth
hikyo backup export --help       a host operator group
hikyo server --help              every server flag, from the flag parser

Anything after -- belongs to the command hikyo run executes and is never read as a request for help.

VerbosityCopy Anchor Link

Use the same repeatable global options with any command. Place them before the command or its other options:

sudo hikyo -vvv upgrade
hikyo -v backup export --out /var/backups/hikyo
hikyo -vv migrate
hikyo -v server
hikyo -vv values import --env staging --from-dotenv .env -o json

Repeat --verbose to increase the level: --verbose --verbose equals -vv. Diagnostics go to stderr; command results, including JSON, stay on stdout. Help and machine-version output retain their normal output contracts. Tokens after -- remain arguments to the child command.

Backup and restore report archive authentication, snapshot export with encryption, validation, data publication and recovery drills. Migration reports signed release checks and actual schema writes; an already-applied schema does not claim another write. Server startup reports configuration, datastore and keyring loading, service/provider preparation and listener setup. Serving readiness is reported separately after serving begins; maintenance mode identifies its restricted listener.

Source imports report parsing, planning and review-artifact creation. Those artifacts are preparation; values import reports the separate application step. Detailed diagnostics use counts and explicitly selected operational metadata. They do not include secret names or values, key material, database connection strings, file paths, request bodies or credential-bearing URLs. Existing command results and errors keep their existing formats.

Server and host operatorCopy Anchor Link

Authentication and local stateCopy Anchor Link

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

Domain resourcesCopy Anchor Link

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

Project key capacityCopy Anchor Link

hikyo project capacity get --org example --project backend
hikyo project capacity set --org example --project backend --max-keys 5000
hikyo project capacity set --org example --project backend --inherit

These human-session commands require project-settings authority. get shows the saved override, instance default and maximum, effective limit, and current key and environment counts. Both commands accept -o table|json.

set requires exactly one of --max-keys N or --inherit. A custom limit must be between 1 and the current instance maximum, whose own ceiling is 10000. --inherit clears the override and follows HIKYO_DEFAULT_KEYS_PER_PROJECT (default 1000). HIKYO_MAX_KEYS_PER_PROJECT is the instance ceiling (default 10000), so one project can use 5000 while other projects inherit 1000.

Lowering the ceiling preserves a larger saved override and caps the effective limit. Existing keys and delivery are preserved. Further key growth must fit the effective limit and the separate 100,000-cell project budget. See managed configuration for the full policy.

Updates read the current policy first and send its revision, instance default and maximum with the write. A concurrent policy change is refused as a conflict; the CLI does not retry the update automatically. Read the policy again and review it before rerunning the intended change.

Deployment adaptersCopy Anchor Link

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 create --provider sealed-webhook --origin URL --env ENV --kind organization --owner RECEIVER_NAMESPACE --prefix PREFIX --keys ID,ID [--stdin|--value-file FILE]
hikyo adapter create --provider gitlab --origin URL --env ENV --kind project|group --owner NAMESPACE [--repo PROJECT] [--scope SCOPE] [--protected] [--hidden] [--expand-variables] [--spki-pin PIN] [--ca-bundle-file FILE] [--allow-personal-token] --prefix PREFIX --keys ID,ID [--stdin|--value-file FILE]
hikyo adapter create --provider aws-secrets-manager --origin https://secretsmanager.REGION.amazonaws.com --env ENV --kind json-object|per-key --owner ACCOUNT_ID [--secret NAME|PATH/] [--kms-key KEY] --aws-auth ambient|assume-role|web-identity|static [--aws-role-arn ARN] [--aws-external-id ID] [--aws-session-seconds N] [--aws-access-key-id ID] [--aws-region REGION] [--aws-sts-origin URL] [--prefix PREFIX] --keys ID,ID [--stdin|--value-file FILE]
hikyo adapter update ADAPTER --origin URL [--keep-remote] [--stdin|--value-file FILE] [--aws-auth MODE ...]
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] [--secret NAME|PATH/] [--kms-key KEY] --prefix PREFIX --keys ID,ID [--keep-remote]
hikyo adapter update ADAPTER --move MOVE --origin URL [--stdin|--value-file FILE] [--aws-auth MODE ...]
hikyo adapter create --provider vault-kv --origin URL[/NAMESPACE] --env ENV --mount MOUNT --path PREFIX --keys ID,ID [--prefix PREFIX] [--stdin|--value-file FILE]

hikyo adapter create --provider cloudflare --env ENV --kind workers-script --account ACCOUNT_ID --script NAME [--prefix PREFIX] --keys ID,ID [--stdin|--value-file FILE]
hikyo adapter create --provider cloudflare --env ENV --kind pages-project --account ACCOUNT_ID --pages-project NAME --destination-environment preview|production [--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] [--aws-auth MODE ...]
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] [--secret NAME|PATH/] [--kms-key KEY] [--scope SCOPE] [--protected] [--hidden] [--expand-variables] --keys ID,ID
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 add --adapter ADAPTER --env ENV --mount MOUNT --path PREFIX --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 machinesCopy Anchor Link

Display-once credentials use a new mode-0600 file, an interactive terminal, or explicit --dangerously-print. Revealed key values also support the protected native clipboard destination described below.

Protected clipboard copyCopy Anchor Link

hikyo values get <KEY> --reveal --clipboard --env <environment>

Add --instance, --org, and --project when they are not selected by your context. This copies the exact revealed value, including multiline or empty values, without printing it. It uses the same reveal capability, audit event, and reauthentication ceremony as values get --reveal.

On macOS, the CLI writes an AppKit pasteboard item with org.nspasteboard.ConcealedType and org.nspasteboard.TransientType. On Windows, it writes native Unicode text with ExcludeClipboardContentFromMonitorProcessing and zero-valued CanIncludeInClipboardHistory and CanUploadToCloudClipboard formats. Supported clipboard managers must honor these markers; the CLI cannot prevent a manager that ignores them from recording the value. The value stays in the live clipboard until replaced; this command does not schedule a clear.

--clipboard requires --reveal and cannot be combined with --output-file, --dangerously-print, or -o json. Unsupported operating systems and clipboard failures are refused, with no plaintext printing fallback. On macOS, the command uses the system /usr/bin/osascript with a fixed AppKit script and supplies the value through stdin, keeping plaintext out of process arguments and files.

On Windows, format registration and buffer preparation finish before the previous clipboard contents are replaced. If clipboard cleanup fails after publication and removal cannot be confirmed, the CLI warns that the value may remain available to paste.

Target flagsCopy Anchor Link

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

Workload deliveryCopy Anchor Link

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. For local runs from scripts and coding agents, see local development and coding agents.

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.

file-target binds a workload service account to one environment and key selection (human session). list and show require manage-adapters; create, update and delete additionally require manage-identities. file-sync is the client on the destination host (machine credential only): it renders the bound target into the directory its local config names and publishes the files as one generation. See File sync.

hikyo file-target list|show|create|update|delete ...
hikyo file-sync render --config FILE [--token-file PATH]
hikyo file-sync doctor --config FILE [-o table|json]

Exit codesCopy Anchor Link

Code 5 deliberately combines missing and unauthorized resources. Code 7 means the server is up and throttling this caller; before it existed a throttled call exited 6.

Rate limitsCopy Anchor Link

A throttled request answers 429 with a Retry-After header. When the refusing limit is a rate window (the per-IP allowance, discovery, the export and other budgets), the value is the whole seconds until that window admits the caller again, absent new traffic. When no reopening time is known (the admission queue, concurrency caps, per-account backoff), it is a fixed five-second hint, not a guarantee. The CLI exits 7 and prints the value on stderr, for example hikyo: too many requests; Retry-After: 23.

Machine values export reads are idempotent, so the CLI re-sends a throttled one after the advertised wait, at most twice and never waiting more than 60 seconds in total. A longer wait is reported at once instead of slept.

Paths that verify a presented credential with expensive work (password login, recovery, and OIDC federation tokens presented by CI jobs and workloads) share a per-source-IP allowance of 10 attempts per sliding minute. The discovery endpoint the CLI calls before each command has its own 60 per minute. The delivery read behind a machine values export shares 300 per minute per organization; a human export is limited to 5 per minute. Every CI job behind one runner egress address draws on the same per-IP allowance. On shared egress:

• run values export once per job and reuse its output for every later step, rather than exporting per step or per service;
• spread parallel jobs that authenticate with federation tokens over time, or give runners distinct egress addresses;
• branch on exit 7 and honour Retry-After rather than retrying on a fixed short interval, which only renews the window.

Import and migrationCopy Anchor Link

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.

Running hikyo import without --from or --mapping on a terminal enters the interactive, multi-environment wizard. Off a terminal the same invocation refuses explicitly and directs you to the flag and mapping modes.

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.

DefinitionsCopy Anchor Link

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] [--confirm-widening <principal>]...

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.

Managed Hikyo configurationCopy Anchor Link

Owner runtime settings and per-node settings are managed through Hikyo itself: edit the protected project, publish an exact revision, reauthenticate and apply with instance-config apply. Manage Hikyo with Hikyo covers adoption, per-node convergence, independent remote projects and rollback, and configuration rollouts covers the controlled bootstrap rollouts for settings that need a restart.