Create your first project

This guide starts after the local server and first administrator exist. It creates a small project and writes one non-secret configuration value. Use the same working directory as the getting-started guide, where the local server’s owner-only .hikyo-runtime socket directory was created.

Prefer the browser? Operate Hikyo from the browser covers the same journey, and the rest of the lifecycle, from the embedded web UI without the CLI.

You will copy opaque IDs from JSON output. Hikyo accepts names in some places, but IDs keep every target explicit while learning the model.

1. Log in and enrol a second factorCopy Anchor Link

hikyo login http://127.0.0.1:8080 --local --as admin --socket "$PWD/.hikyo-runtime/hikyo.sock"
hikyo account factor enrol-totp --output-file ./hikyo-otpauth-uri
hikyo account factor confirm-totp
hikyo account factor step-up
hikyo whoami -o json

Import the provisioning URI into an authenticator before confirming it. Use a fresh code for confirmation, then another fresh code for step-up. Delete the URI file after confirmation.

Organisation creation requires recent multi-factor assurance. This is why the quick path does not skip account security.

2. Create an organisationCopy Anchor Link

hikyo org create --name demo -o json

Copy the organisation id. Also copy principal.id from hikyo whoami -o json if you need it for later membership administration. Creation atomically grants the creator the organisation admin template.

Changing your own grants revokes your current session. Organisation creation performs that change automatically. Log in and step up again before continuing:

hikyo login http://127.0.0.1:8080 --local --as admin --socket "$PWD/.hikyo-runtime/hikyo.sock"
hikyo account factor step-up

3. Create a project and environmentsCopy Anchor Link

hikyo project create --org <org-id> --name checkout -o json
hikyo env create --org <org-id> --project <project-id> --name development -o json
hikyo env create --org <org-id> --project <project-id> --name production -o json

Copy the project ID and both environment IDs from the responses. Values do not inherit between environments; each cell starts as absent.

4. Save a local contextCopy Anchor Link

hikyo context create checkout-dev \
  --instance http://127.0.0.1:8080 \
  --org <org-id> \
  --project <project-id> \
  --env <development-env-id>

hikyo context show checkout-dev

A context stores targets, not credentials. Hikyo has no global active context, so each command names it with --context.

5. Declare, stage and publish a valueCopy Anchor Link

hikyo key create \
  --context checkout-dev \
  --name LOG_LEVEL \
  --classification config \
  --declaration '{"rule":{"type":"string"}}'

printf '%s' 'debug' > ./log-level.txt
hikyo values set LOG_LEVEL \
  --context checkout-dev \
  --value-file ./log-level.txt
rm ./log-level.txt
hikyo values publish --context checkout-dev --versions <version-id-from-set>

The declaration is saved before the value. Keep the key ID printed by key create for the inspection step. values set reports the pending version ID to use for publication. Publication validates the value against its declaration and tracks presence independently in each environment. This example leaves the key optional so production may remain absent.

6. Inspect the resultCopy Anchor Link

hikyo key show <key-id-from-create> --context checkout-dev
hikyo values get LOG_LEVEL --context checkout-dev
hikyo values diff \
  --context checkout-dev \
  --left <development-env-id> \
  --right <production-env-id>

The diff should show LOG_LEVEL set in development and absent in production. No value silently falls through from one environment to another.

Next: learn the value workflows or connect a workload with a machine identity.