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 presence

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.

Set from a protected file

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 terminal

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 value

hikyo values set OPTIONAL_ENDPOINT --context production --clear

Clear records absent. Hikyo refuses the change when the declaration requires the key in that environment.

Compare environments

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 values

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

Copy is explicit about source, destinations, and keys. Protected destinations require the extra confirmation flag and the corresponding authorization.

Reveal one secret

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 .env

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 file

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).

Next: connect automation.