Value workflows

These workflows assume the instance is trusted, the user is logged in, and the target resolves through flags, environment, a pin file, or a context.

Inspect presenceCopy Anchor Link

hikyo values list --context production
hikyo values get DATABASE_PASSWORD --context production

An ordinary secret read returns metadata and presence, not plaintext. Use this path for inventory and health checks.

Stage and publishCopy Anchor Link

values set stages a pending change and reports its version ID; delivery continues to use the previous publication. Publish the intended versions explicitly, after reviewing them:

hikyo values publish --context production --versions <version-id,version-id>

Publishing selected versions can also publish related pending versions required by key-group closure. Review the complete set, including related drafts, before running the command.

Publication needs publish separately from edit, validates the complete resulting state and applies protection and change-approval policies.

values import and values copy are immediate bulk publications with their own authorization and validation gates; they do not use this separate draft publication step.

Set from a protected fileCopy Anchor Link

hikyo values set DATABASE_PASSWORD \
  --context production \
  --value-file /run/secrets/new-database-password

The value file is read locally. Keep its permissions narrow and remove it when its owning secret-delivery mechanism does not manage its lifecycle.

Set from the terminalCopy Anchor Link

hikyo values set FEATURE_MODE --context production --stdin

Type the value, then end input. Do not put a value after a command-line flag. Command arguments are visible through shell history and process inspection.

Clear a valueCopy Anchor Link

hikyo values set OPTIONAL_ENDPOINT --context production --clear

Clear stages an absent draft. Saving it is allowed even for a required key; publication refuses to leave that key absent. The published value remains available until a valid publication changes it.

Compare environmentsCopy Anchor Link

hikyo values diff \
  --context production \
  --left development \
  --right production

The ordinary diff compares state without exposing secret plaintext. Add reveal only when the comparison requires it and write the result to a protected file.

Copy selected valuesCopy Anchor Link

hikyo values copy \
  --context production \
  --from staging \
  --to production \
  --keys API_BASE_URL,FEATURE_MODE

Copy is explicit about source, destinations, and keys. It publishes immediately after authorization and validation. Human copies into protected destinations require the purpose-bound reauthentication ceremony; --confirm-protected does not replace that ceremony. Machine copies require the explicit protected-target confirmation in addition to their authorization.

Reveal one secretCopy Anchor Link

hikyo values get DATABASE_PASSWORD \
  --context production \
  --reveal \
  --output-file ./database-password

The output path must not already exist. Consume it, then remove it through your normal secure-file procedure.

A disclosure needs a reauthentication window over the environment. When none is live the CLI opens one: where the environment’s effective window is above 0 it prompts for an authenticator code at the terminal; where it is 0 (a protected environment, or an instance that keeps the production default HIKYO_REAUTH_WINDOW_SECONDS=0) a code cannot bind the decision, so the CLI opens the browser to the same purpose-bound passkey ceremony the Values page runs, naming exactly the secret keys the command will open, and continues once you approve. Either way the session token rotates and is stored. --dev instances default to a 15-minute window; raise an environment’s window with hikyo project-settings set --env <env-id> --reauth-window-seconds 300.

Import an existing .envCopy Anchor Link

The schema is closed: values import refuses undeclared keys. To onboard a .env you already have, first scaffold a declaration for every key, review it, apply it, then import the values.

hikyo definitions scaffold --from .env > definitions-bundle.json

scaffold is offline. It contacts no server, reads only the file you give it, and emits an additive bundle in which every key is config with a TODO: classify marker. It cannot know which keys are secret, so it does not guess. Open the bundle, change each secret key’s classification, then apply it:

hikyo definitions plan --file definitions-bundle.json
hikyo definitions apply --plan <plan-id> --file definitions-bundle.json

With the keys declared, import the values through the same strict path:

hikyo values import --context production --from-dotenv .env

Any key still not declared is refused by name. That surfaced typo is the point. After a successful import the source .env is still plaintext on disk; delete it once the values have landed.

Export as a dotenv fileCopy Anchor Link

hikyo values export --context production --format dotenv --reveal --output-file ./.env

--format selects table, json, or dotenv. The dotenv payload is escaped exactly as the Compose renderer would deliver it. Without --reveal every secret is omitted and their count is reported on stderr; with --reveal the output carries plaintext and obeys the print triad (a new file, the terminal, or explicit --dangerously-print).

For a development workstation or a coding agent, compare this with delivering straight into the process in Local development and coding agents.

Next: connect automation.