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.

These examples use the checkout-dev context created in First project, steps 1–4. That setup creates an organisation, project and development environment, then saves their IDs and the instance in a named context. Check it with hikyo context show checkout-dev before continuing. Every command below selects that context explicitly; there is no global active context.

Declaration before valueCopy Anchor Link

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 \
  --context checkout-dev \
  --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 secretCopy Anchor Link

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

Presence rulesCopy Anchor Link

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

Stage, publish, clear, and replaceCopy Anchor Link

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

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

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

Both commands save drafts and report a version ID; they do not change delivered values. Publish the selected version explicitly:

hikyo values publish --context checkout-dev --versions "$VERSION_ID"

Set VERSION_ID to the version ID returned by the draft command you intend to publish. The set and clear examples are alternatives; publishing the clear leaves the key absent.

Drafts may be incomplete or invalid. Publication validates the resulting state and refuses schema failures, required keys left absent, forbidden keys set and incomplete all-or-none groups.

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

Reveal safelyCopy Anchor Link

Before using this example, declare DATABASE_PASSWORD as a secret in checkout-dev, stage its value from a protected file and publish the returned version as described above. You can instead reveal another secret already published in that context.

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 \
  --context checkout-dev \
  --reveal \
  --output-file ./db-password

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

Next: follow the value workflows.