Skip to content

Key Management CLI — Commands Reference

Binary: ankasecure-km
Version: 3.4.0

Every command is ankasecure-km <group> <verb> [options], except init and view-session. No command takes a tenant: the workload's token names it. Path and query parameters are options; a request body comes from --body-file <json> (- reads standard input), with convenience options for the common members, which are set over the file's content. A member the request model does not declare is refused (E_BAD_BODY, naming the member, never its value).

Global options

Option Meaning
--format json\|table Output format; json is the default
--help, -h Usage of the command
--version, -V The CLI's version

Listing commands that page accept --page <n> (zero-based), --size <n> and --sort <property[,asc|desc]>.

Exit codes

Code Meaning
0 Success, including an operation that now waits for quorum approval
1 A user error the command detects (missing or conflicting configuration, E_BAD_URL, E_BAD_UUID, E_BAD_BODY, E_TOKEN_COMMAND_NOT_ALLOWED, ...)
2 A usage error, or an authentication or authorization failure (E_AUTH_FAILED, E_AUTHZ_FORBIDDEN)
3 Any other server refusal (404, 409, 422, other 4xx, 5xx) or an unexpected failure
4 An IO or network failure

A usage error prints the usage and sends nothing. A server refusal prints the server's problem type.

Pending quorum approval

A destruction request, and an operation the tenant's quorum policy gates, print on stdout (with --format json):

{"status":"PENDING_APPROVAL","quorumRequestId":"8d2e4f60-1a3b-4c5d-9e7f-0a1b2c3d4e5f","operation":"KEY_MARK_FOR_DESTRUCTION",
 "target":"old-archive-key","requiredApprovals":1,"approvals":0,"expiresAt":"2026-11-09T09:15:00Z"}

and the human-readable lines on stderr, and exit 0. Approval and rejection are made in the Admin Console; quorum-requests reads and cancels the workload's own requests.

init

Option Required Meaning
--url <origin> Yes The deployment's address: an absolute https URL with a host (http for development). An address without a scheme or a host is refused with E_BAD_URL (exit 1); without a port, the scheme's own port is dialled
--workload-id <uuid> Yes The administrative workload
--private-key-file <path> One of three A PKCS#8 PEM or private JWK file, owner-only
--token-file <path> One of three A file holding a federated token
--token-command <cmd> One of three A command that prints a federated token; runs only with ANKASECURE_ALLOW_EXTERNAL_TOKEN_COMMAND=1, split on whitespace outside quotes, never through a shell
--auth-url <origin> No Where the CLI obtains its token, when that differs from --url; saved with the configuration. Defaults to --url; checked as --url is
--insecure No Disables TLS verification, persisted, warned on every command
--force No Replaces an existing configuration

init authenticates once, then writes the address, the workload id and the credential reference — never a key, token or secret.

view-session

Prints the workload id, the tenant, the token's expiry, its scopes and the endpoint; never the token.

keys

Verb Options
list --status, --origin, --restricted <true\|false>, --kty, --conformance, paging
get --kid
create --kid, --algorithm, --kty, --purpose, --key-ops <op,...>, --exportable <true\|false>, --body-file
update --kid, --body-file (a JSON Merge Patch of the metadata)
import-key --body-file
import-keystore, analyze-keystore --keystore-file <path>, --metadata-file <json\|->, and --password-stdin or --password-prompt
export --kid
lifecycle-cause-verdicts --kid
supported-algorithms --category, --status, --min-security-level, --max-security-level, --key-ops, --standards, --kty, --alg, --composite-mode
suspend, revoke --kid, --cause, --reason, --body-file
reactivate, archive --kid

The keystore password is read from standard input to its end (--password-stdin, one trailing newline removed, at most 4,096 bytes) or from the console without echo (--password-prompt), never as an option value, and zeroed after the request.

materials

Verb Options
list --kid
get --kid, --material-version <n>
revoke --kid, --material-version <n>, --cause, --reason, --body-file

rotation

Verb Options
rotate --kid, --body-file, --idempotency-key <key>
admissibility --kid
schedule --kid
replace-schedule --kid, --body-file
executions --kid, --page, --size

destruction

Verb Options
request-key --kid, --cooling-off-days <7..365>, --body-file
cancel-key --kid
request-version --kid, --material-version <n>, --cooling-off-days <7..365>, --body-file
cancel-version --kid, --material-version <n>
orders --kid

See Key Destruction for the workflow.

quorum-requests

Verb Options
list --status, --page, --size
get --id <uuid>
cancel --id <uuid>

exchange-contexts

Verb Options
list paging
list-for-application --application-id <uuid>
get, delete, resume, close --id <uuid>
create --application-id <uuid>, --body-file
update --id <uuid>, --body-file
suspend --id <uuid>, --reason, --body-file

exchanges

Verb Options
list --status, --counterparty, --application-id, --owner-principal-id, --name-search, --page, --size, --sort-by, --sort-direction <asc\|desc>
create --body-file
get, validate --id <uuid>
update --id <uuid>, --body-file
discard-draft --id <uuid>, --expected-version <n>
clone --id <uuid>, --name, --body-file
preview-activation --id <uuid>, --capability
activate --id <uuid>, --expected-version <n>, --capability, --body-file
suspend, revoke --id <uuid>, --expected-version <n>, --reason, --body-file
resume --id <uuid>, --expected-version <n>, --body-file

capability-grants

Verb Options
list --actor-id, --asset-kid, --exchange-context-id, --constraint-policy-id, paging
create, preview --body-file
get, delete --id <uuid>

constraint-policies

Verb Options
list paging
create --body-file
get, delete --id <uuid>
update --id <uuid>, --body-file

internal-crypto-use-cases

Verb Options
list --status, paging
create --body-file
get, resume --id <uuid>
delete --id <uuid>, --reason
suspend --id <uuid>, --reason, --body-file

create prints the new use case's client secret once, inside credential.clientSecret on stdout, and never writes it to a file or a log. Store it at once.

directory

Verb Options
list-applications, list-actors paging
get-application, list-application-actors --application-id <uuid>
get-actor --actor-id <uuid>
list-counterparty-types —
get-counterparty-type --id <uuid>

CLI Version: 3.4.0
Last updated: 2026-10-26