Values and secrets

A key declaration defines what a value is allowed to be. Each environment then records that key as either set or absent.

Declaration before value

Create the catalogue entry before writing values. The declaration and presence rules are project-wide; only the value state varies by environment.

hikyo key create \
  --name API_BASE_URL \
  --classification config \
  --declaration '{"rule":{"type":"url","schemes":["https"]}}'

Declaration JSON is metadata, not a value. The CLI rejects unknown fields and constraints that do not belong to the declared type. Use hikyo key show to inspect the stored declaration before setting values.

Configuration or secret

Classification is a security boundary. Change it with key reclassify, never as an incidental metadata update.

Presence rules

• Required means the environment must contain a set value.
• Forbidden means the environment must keep the key absent.
• Optional permits either state.

A rule can apply to all environments or an explicit set. The same environment cannot be both required and forbidden.

Set, clear, and replace

Values never belong on argv. Read them from standard input or a protected file:

hikyo values set API_BASE_URL --value-file ./api-base-url.txt
hikyo values set API_BASE_URL --clear

For an interactive value, --stdin reads from standard input. For automation, prefer a protected file supplied by the workload’s secret store.

Replacing a secret does not reveal the old secret. Clearing changes its state to absent; it does not store an empty string.

Reveal safely

Secret reads are masked unless you request --reveal. Revealed output must go to a new mode-0600 file or through the explicit terminal warning.

hikyo values get DATABASE_PASSWORD \
  --reveal \
  --output-file ./db-password

Avoid --dangerously-print in terminals with scrollback, recording, shared logs, or command capture.

Next: follow the value workflows.