AnkaSecure CLI – Command Reference
CLI build version: 3.0.0 Executable: AnkaSecureCLI
Invocation pattern:
AnkaSecureCLI <command> [options]
The CLI is a thin wrapper over the AnkaSecure API—all cryptographic work happens server-side.
Global flags available on every command:
| Flag | Purpose |
-h, --help | Print command-specific usage. |
-V, --version | Display CLI build version. |
--config-path=<file> | Use an alternate cli.properties file. |
Table of Contents
- Initialisation
- Key Lifecycle
- Algorithm Discovery
- Non-Streaming File Crypto
- Streaming File Crypto
- Public-Key Utility Streams
- Operational Limits
- Best Practices
Initialisation
init
| Option | Required | Description |
--force | | Overwrite an existing credential store. |
--silent | | Non-interactive mode. All credentials must be passed via flags. |
--client-id=<id> | when --silent | Application clientId issued by AnkaSecure. |
--client-secret=<secret> | when --silent | Application clientSecret issued by AnkaSecure. |
--config-path=<file> | | Alternate location for cli.properties. |
Initialises an AES-GCM–encrypted credential store. Must be run once before any other command.
Key Lifecycle
The administrative key commands moved to the Admin CLI in 3.0.0
generate-key, import-key, import-key-pkcs12, export-key, remove-key, revoke-key, patch-key and create-rotation are not part of this CLI. They moved to the unified Admin CLI (ankasecure-admin) as part of the 3.0.0 release, and their option tables were documented here for a build that no longer offers them.
| Was documented here | Now |
generate-key | ankasecure-admin key create |
import-key, import-key-pkcs12 | ankasecure-admin key import |
export-key | ankasecure-admin key export |
patch-key | ankasecure-admin key patch |
create-rotation | ankasecure-admin key rotate |
revoke-key | ankasecure-admin key revoke — now requires --reason |
remove-key | ankasecure-admin key archive then key delete (two-step) |
key suspend, key revoke and key revoke-material each require a --reason, at most 1,000 UTF-8 bytes, which is signed into the admin audit trail. The retired revoke-key documented here never had one.
This CLI retains the read-only key command below; every mutating key operation is an administrative action and lives in the Admin CLI.
list-keys
Return metadata for stored keys. By default the command auto-paginates and returns ALL matching keys (pages are fetched from the server one by one until the inventory is exhausted). All filters are applied server-side before pagination, so totals always reflect the filtered count.
| Option | Description |
--origin=<origin> | Filter by key origin — the two published origins: GENERATED, IMPORTED. The accepted set and the --help text are both derived from the SDK's KeyOrigin enum, so they cannot drift from the wire. |
--restricted=<bool> | Filter by restriction status: true (restricted only), false (unrestricted only). |
--kty=<kty> | Filter by key type. Takes a published key-type token — the same value the kty column shows: ML-KEM, HQC, FRODO, CMCE, BIKE, SABER, NTRU, NTRUPRIME, ML-DSA, SLH-DSA, FALCON, XMSS, LMS, EC, RSA, oct, OKP, SM2, GOST-EC, or COMPOSITE for every hybrid pairing. A composite mode name is not a key type and is rejected. |
--status=<status> | Filter by lifecycle status. Takes a published key-status token — the same value the status column shows: active, pending_rotation, rotated, expired, revoked, archived, deleted_logical, suspended, pending_destruction. Matching is case-insensitive on the client; any other value is rejected before the request is sent. |
--limit=N | Stop fetching once N keys are collected (must be >= 1). When more keys match, the output is prefixed with Showing first N of M keys. Without --limit, ALL matching keys are returned. |
--format=<fmt> | Output format: table (default), detailed, json. The accepted set, the help text and the renderer are one closed vocabulary — an unrecognised value is a usage error, never a silent fallback. |
--config-path=<file> | Alternate properties file. |
Algorithm Discovery
get-supported-algorithms
Retrieve the supported algorithm catalogue with optional server-side filtering.
Filter Options:
| Option | Type | Description |
--kty=<types> | comma-separated | Filter by key type(s): ML-KEM, ML-DSA, SLH-DSA, FALCON, RSA, EC, oct, OKP, … or COMPOSITE, which selects every hybrid pairing |
--alg=<algorithms> | comma-separated | Filter by algorithm(s): ML-KEM-768, RSA-4096, etc. |
--category=<category> | string | Filter by category: CLASSICAL, POST_QUANTUM, HYBRID — all three, derived from the SDK's AlgorithmInfo.Category |
--status=<status> | string | Filter by status: RECOMMENDED, LEGACY, EXPERIMENTAL — all three, derived from the SDK's AlgorithmInfo.Status |
--key-ops=<ops> | comma-separated | Required operations: encrypt, decrypt, sign, verify |
--security-level=<n> | integer | Exact NIST security level: 1, 3, or 5 |
--min-security-level=<n> | integer | Minimum NIST security level (inclusive) |
--max-security-level=<n> | integer | Maximum NIST security level (inclusive) |
--standards=<standards> | comma-separated | Required standards: NIST, BSI, ANSSI, etc. |
--composite-mode=<modes> | comma-separated | Composite construction(s): COMPOSITE_KEM_COMBINE, COMPOSITE_SIGNATURE. This is the axis hybrid entries are distinguished on — every one of them publishes kty = COMPOSITE, so --kty no longer separates them |
Output Options:
| Option | Description |
--format=<format> | Output format: table (default), detailed, json. The accepted set, the help text and the renderer are one closed vocabulary — an unrecognised value is a usage error, never a silent fallback |
--count | Show only the count of matching algorithms |
--config-path=<file> | Alternate properties file. |
Filter Logic:
- AND:
--key-ops, --standards (must support ALL specified values) - OR:
--kty, --alg, --composite-mode (matches ANY specified value)
Examples:
# List all algorithms
get-supported-algorithms
# Post-quantum algorithms only
get-supported-algorithms --category POST_QUANTUM
# Recommended algorithms at security level 3+
get-supported-algorithms --status RECOMMENDED --min-security-level 3
# Encryption-capable algorithms in table format
get-supported-algorithms --key-ops encrypt,decrypt --format table
# Count PQC algorithms
get-supported-algorithms --category POST_QUANTUM --count
# JSON output for scripting
get-supported-algorithms --format json | jq '.[].alg'
Non-Streaming File Crypto
encrypt-file
| Option | Required | Description |
--kid=<kid> | ✔︎ | Public key for encryption. |
--input-file=<file> | ✔︎ | Plaintext source. |
--output-file=<file> | ✔︎ | Compact JWE destination. |
--config-path=<file> | | Alternate properties file. |
decrypt-file
| Option | Required | Description |
--input-file=<file> | ✔︎ | Compact JWE source. |
--output-file=<file> | ✔︎ | Plaintext destination. |
--config-path=<file> | | Alternate properties file. |
sign-file
| Option | Required | Description |
--kid=<kid> | ✔︎ | Private key for signing. |
--input-file=<file> | ✔︎ | Data to sign. |
--output-jws-file=<file> | ✔︎ | Compact JWS destination. |
--config-path=<file> | | Alternate properties file. |
verify-signature
| Option | Required | Description |
--jws-file=<file> | ✔︎ | Compact JWS to verify. |
--config-path=<file> | | Alternate properties file. |
reencrypt-file
| Option | Required | Description |
--new-kid=<kid> | ✔︎ | Public key that will protect the refreshed JWE. |
--input-file=<file> | ✔︎ | Original Compact JWE. |
--output-file=<file> | ✔︎ | New Compact JWE. |
--config-path=<file> | | Alternate properties file. |
resign-file
| Option | Required | Description |
--new-kid=<kid> | ✔︎ | Private key for the replacement signature. |
--old-jws-file=<file> | ✔︎ | Original Compact JWS. |
--new-jws-file=<file> | ✔︎ | Refreshed Compact JWS. |
--config-path=<file> | | Alternate properties file. |
Streaming File Crypto
encrypt-file-stream
| Option | Required | Description |
--kid=<kid> | ✔︎ | Public key for encryption. |
--input-file=<file> | ✔︎ | Plaintext source. |
--output-file=<file> | ✔︎ | Detached JWET destination. |
--config-path=<file> | | Alternate properties file. |
decrypt-file-stream
| Option | Required | Description |
--input-file=<file> | ✔︎ | Detached JWET source. |
--output-file=<file> | ✔︎ | Plaintext destination. |
--config-path=<file> | | Alternate properties file. |
sign-file-stream
| Option | Required | Description |
--kid=<kid> | ✔︎ | Private key for signing. |
--input-file=<file> | ✔︎ | Data stream. |
--output-signature-file=<file> | ✔︎ | Detached-JWS destination. |
--config-path=<file> | | Alternate properties file. |
verify-signature-stream
| Option | Required | Description |
--input-file=<file> | ✔︎ | Data stream. |
--input-signature-file=<file> | ✔︎ | Detached-JWS to verify. |
--config-path=<file> | | Alternate properties file. |
reencrypt-file-stream
| Option | Required | Description |
--new-kid=<kid> | ✔︎ | Public key that will protect the refreshed ciphertext. |
--input-file=<file> | ✔︎ | Original detached JWET. |
--output-file=<file> | ✔︎ | New detached JWET. |
--source-kid-override=<kid> | | Override when legacy JWE header lacks kid. |
--config-path=<file> | | Alternate properties file. |
resign-file-stream
| Option | Required | Description |
--new-kid=<kid> | ✔︎ | Private key for new signature. |
--old-signature-file=<file> | ✔︎ | Existing detached-JWS. |
--input-file=<file> | ✔︎ | Data stream. |
--new-signature-file=<file> | ✔︎ | Refreshed detached-JWS. |
--config-path=<file> | | Alternate properties file. |
Public-Key Utility Streams
encrypt-file-publickey-stream
Encrypt with a caller-supplied public key (not stored server-side).
| Option | Required | Description |
--kty=<kty> | ✔︎ | Key type. |
--alg=<alg> | ✔︎ | Algorithm / parameter set. |
--public-key=<json> | ✔︎ | JSON file holding ExportedKeySpec.publicKey. |
--input-file=<file> | ✔︎ | Plaintext source. |
--output-file=<file> | ✔︎ | Detached JWET destination. |
--config-path=<file> | | Alternate properties file. |
verify-signature-publickey-stream
Verify with a caller-supplied public key.
| Option | Required | Description |
--kty=<kty> | ✔︎ | Key type. |
--alg=<alg> | ✔︎ | Algorithm / parameter set. |
--public-key=<json> | ✔︎ | JSON file holding ExportedKeySpec.publicKey. |
--input-signature-file=<file> | ✔︎ | Detached-JWS to verify. |
--input-file=<file> | ✔︎ | Data stream. |
--config-path=<file> | | Alternate properties file. |
Operational Limits
| Resource | Default (Demo tenant) |
| Max JSON payload | 5 MiB |
| Max streaming chunk size | 5 MiB |
| Access-token lifetime | 1 h |
| Refresh-token lifetime | 72 h |
Custom limits are available for production tenants—contact support.
Best Practices
- Run
init once per environment; never store plaintext credentials. - Use
*-stream commands for any artefact larger than 5 MiB. - Rotate keys with
create-rotation and leverage warnings in API responses. - Query
get-supported-algorithms before generate-key to enforce policy. - Gate CI/CD jobs on CLI exit codes—non-zero means failure.
© 2025 ANKATech Solutions INC. All rights reserved.
Relative links ensured for seamless MkDocs integration.