Secrets commands (source preview)

axiom secrets manages write-only secret values in Axiom Cloud, administers secret environments, and selects local or Cloud secret profiles for a running backend. Values never enter compilation.

Check the executable you intend to use:

axiom --version
axiom secrets --help

If secrets is unknown, use the dashboard. Installing the public CLI does not enable this preview. Check the target limits in Support and availability before you try runtime consumption.

Command summary

All Cloud rows take --project PROJECT; the rows marked with an environment also take --environment ENVIRONMENT_ID. Cloud commands need axiom login.

Inputs and output

Run local commands from the application directory that contains AxiomSecrets.toml. The optional ROOT defaults to .. Browser sign-in and CLI device login are separate sessions.

Cloud commands print JSON metadata, never saved values. The identifiers below are placeholders. There is no command to read, reveal or export a saved value, and no automatic whole-dotenv import.

Manage Cloud environments

axiom login
axiom secrets environments --project payments-api
axiom secrets create-environment --project payments-api \
  --slug staging-payments --kind staging
axiom secrets create-environment --project payments-api \
  --slug production --kind production --protected

Creation returns an id. Kinds are development, staging, production and preview. Production requires --protected. A preview requires --expires-at RFC3339_TIMESTAMP, in the future and no more than seven days away. New environments inherit no values or grants. See Secrets for environment rules and roles.

Owners update an environment through a private metadata file. This example disables an unprotected staging environment. Replace the revision with its current value and keep the actual protection and expiry settings:

{
  "status": "disabled",
  "protected": false,
  "expected_revision": 1,
  "expires_at": null
}

chmod 600 environment-update.json
axiom secrets update-environment --project payments-api \
  --environment ENVIRONMENT_ID --file environment-update.json

status is active or disabled. Production cannot become unprotected. A preview update needs a valid future expiry within seven days. An update invalidates existing leases; enabling does not restore revoked access.

Define, save and activate

axiom secrets define payments/api-key --project payments-api \
  --purpose authenticateHttp --description "Payment provider authentication"
axiom secrets list --project payments-api
axiom secrets set SECRET_ID --project payments-api --environment ENVIRONMENT_ID
axiom secrets versions SECRET_ID --project payments-api --environment ENVIRONMENT_ID

define returns a secret ID. Purposes are authenticateHttp, signRequest, verifyToken, connectDatabase and authenticateWorker. --description defaults to an empty string. list returns project-wide definitions, not values of the selected environment.

set opens a masked prompt. It saves a candidate and returns metadata including its ID; it does not activate the value or authorize its use. For automation, --stdin reads one raw credential of 1 to 65,536 bytes:

axiom secrets set SECRET_ID --project payments-api \
  --environment ENVIRONMENT_ID --stdin < /private/path/payment-key

Keep that input owner-only and outside version control. Stdin keeps every byte, including a trailing newline. Do not pass a whole .env document, or put a value in a command argument, shell history, build log or description.

versions returns up to 200 recent versions with UUID, numeric version, status, creation time and destruction eligibility. It does not return the mutation revision. As an owner, get the current environment-secret revision (see below), then review and activate the intended candidate:

axiom secrets activate SECRET_ID VERSION_ID --project payments-api \
  --environment ENVIRONMENT_ID --revision CURRENT_REVISION

Refresh metadata after each successful change. On a revision conflict, re-read and review before you retry. Activation leaves explicit runtime pins and running generations unchanged. A connection failure can leave a write unconfirmed: inspect metadata before you submit a value again.

Revision metadata

Version actions use the environment-secret revision, not the numeric version or the environment's revision. The preview CLI has no environment-secret inventory or binding list command. The authenticated management API exposes the missing reference metadata through these read-only routes:

Use an authorized native management session for API requests. Do not copy a browser cookie or put tokens in a URL. axiom secrets environments supplies the separate environment revision for update-environment. The dashboard reads these revisions for you if you prefer to manage changes there.

Bind and grant

These commands require an owner. JSON files passed with --file must be owner-only regular files, without symlinks or multiple hard links, and at most 32,768 bytes. They contain reference metadata, never a credential.

Inspect a compiled private backend plan:

axiom secrets requirements backend.server.json

The result includes planSha256, declared requirements and resource consumers. It is not a complete catalog of authentication or sandbox consumers: use the exact compiled plan and the reviewed consumer declaration.

This binding template uses HTTP authentication. Replace every placeholder and review the origin, method and path restriction:

{
  "secret_id": "SECRET_UUID",
  "requirement": "payment",
  "consumer": "resource:payments",
  "purpose": "authenticateHttp",
  "plan_sha256": "EXACT_64_CHARACTER_LOWERCASE_SHA256",
  "package_sha256": null,
  "version": 1,
  "destination_policy": {
    "origin": "https://api.payment-provider.example",
    "method": "POST",
    "path_prefix": "/payments"
  },
  "expected_revision": 0
}

Use expected_revision: 0 to create and the current binding revision to update. version: null follows the active version during eligible new resolution. Sandbox consumers also need the exact canonical package fingerprint, and their deployment injection remains a separate explicit requirement.

chmod 600 binding.json
axiom secrets bind --project payments-api \
  --environment ENVIRONMENT_ID --file binding.json

A separate grant authorizes one project member in an unprotected development or staging environment. Set a future RFC 3339 expiry no more than 90 days away:

{
  "binding_id": "BINDING_UUID",
  "user_id": "PROJECT_MEMBER_UUID",
  "workload_id": null,
  "expires_at": "FUTURE_RFC3339_TIMESTAMP"
}

chmod 600 grant.json
axiom secrets grant --project payments-api \
  --environment ENVIRONMENT_ID --file grant.json
axiom secrets grants --project payments-api --environment ENVIRONMENT_ID

For a workload, set workload_id and user_id: null. Register the exact workload first with register-workload --file workload.json. Its JSON fields are issuer (https://accounts.google.com), subject (the Google identity token subject), audience (the configured secret runtime audience), plan_sha256 and an optional deployment_id. The Cloud runtime audience is https://api.axiomcore.dev/runtime/v1/secret-leases. Registration does not grant access or qualify an unsupported runtime target.

Select local and Cloud profiles

axiom secrets init . creates a reference-only AxiomSecrets.toml scaffold and refuses to overwrite an existing file. Edit it to select each source explicitly. This complete minimal file defines one local requirement:

format = "axiom-secret-bindings/v1"

[environments.development.secrets.payment]
source = "dotenv"
file = ".env.development"
key = "PAYMENT_KEY"

Put PAYMENT_KEY in your private .env.development, set its mode to 0600, and keep it out of version control and public assets. The file must belong to the runtime user, stay inside the selected root and have one hard link. Do not source it into a shell. There is no parent discovery, interpolation, shell execution or automatic fallback to another source.

chmod 600 .env.development
axiom secrets inspect . --environment development
axiom secrets check . --environment development
axiom secrets check . --environment development --resolve

inspect shows references. check validates configuration; --resolve also checks local sources without printing values. For this file, a successful resolved check prints:

{"bindings":["payment"],"resolved":true,"valid":true}

A Cloud profile also supplies exact project, environment and binding IDs. Add this partial section to the same file, replacing the placeholders:

[environments.cloud-staging.secrets.payment]
source = "axiom-cloud"
secret = "payments/api-key"
version = "1"

[environments.cloud-staging.cloud]
identity = "development"
project_id = "PROJECT_UUID"
project_slug = "payments-api"
environment_id = "ENVIRONMENT_UUID"

[environments.cloud-staging.cloud.bindings]
payment = "BINDING_UUID"

version is an immutable numeric version written as a string. Development identity needs an eligible environment and a separate member grant. A Cloud profile cannot use check --resolve: its authorization is validated against the exact executable plan when the supported runtime starts.

For an existing compiled application with a reviewed deployment configuration, the preview's serve accepts an --environment profile (not available in CLI 0.149.1):

axiom serve service.acore --deployment deployment.json \
  --environment development --watch --port 8080

Use --environment cloud-staging to select the Cloud profile instead. This is a runtime invocation template, not a complete application: its Acore declaration, consumer, private plan, deployment and Cloud binding must agree. Compilation does not read value files. With --watch, a replacement generation is prepared before new requests switch to it; a failed replacement keeps the old generation, subject to expiry and revocation. Runtime secrets are unavailable in mock execution. See Secrets at runtime.

Failure cases and cleanup

Invalid or missing profiles, unsafe file ownership, mode or linking, unavailable identity, mismatched fingerprints, expired grants, disabled scopes and stale revisions fail closed. An unsupported protected target is rejected. An audit or Cloud outage can deny use of a value even before a lease expires. Use metadata and the dashboard's activity view to investigate; do not add credential dumps to troubleshoot.

After testing, revoke temporary grants and disable temporary workloads and environments. Remove local credential files through your normal private-file cleanup. Continue with Secrets for lifecycle and rotation, or Secrets at runtime for the runtime security model.