CLI Reference

Complete reference for all Arcan CLI commands. The CLI communicates with the Arcan server over HTTPS.

Global Flags

These flags apply to all commands:

Flag	Default	Description
`--api-url`	`http://localhost:8081`	Arcan server URL
`--debug`	`false`	Enable verbose debug output
`--version`		Print version information

Server & Setup

`arcan server`

Start the Arcan server in standalone (SQLite) or multi-node (PostgreSQL) mode.

arcan server [flags]

Flags:

Flag	Short	Default	Description
`--port`	`-p`	`8081`	Port to listen on
`--host`		`0.0.0.0`	Host to bind to
`--data-dir`		`~/.arcan/data`	Data directory for database, keys, certs, plugins
`--database-url`			PostgreSQL connection string (enables multi-node mode)

Environment variables:

Variable	Description
`ARCAN_PORT`	Overrides `--port`
`ARCAN_DATA_DIR`	Overrides `--data-dir`
`ARCAN_DATABASE_URL`	Overrides `--database-url`
`DATABASE_URL`	Fallback for `--database-url`
`ARCAN_JWT_SECRET`	JWT signing secret (default: dev secret)

Examples:

# Start in standalone mode (SQLite, auto-generated encryption key)
arcan server

# Custom port
arcan server --port 9090

# Custom data directory
arcan server --data-dir /var/arcan

# Multi-node mode with PostgreSQL
arcan server --database-url postgres://user:pass@localhost:5432/arcan

Notes:

On first start with no users, an interactive setup wizard runs to create the admin account.
TLS is always enabled. A self-signed CA and server certificate are auto-generated in the data directory.
Send SIGHUP to reload SSO configuration without downtime. SIGINT/SIGTERM triggers graceful shutdown.

`arcan login`

Save server URL and API token for CLI use. Credentials are stored in ~/.arcan/config.yaml.

arcan login [flags]

Flags:

Flag	Default	Description
`--server`		Arcan server URL (prompted if omitted)
`--token`		API token (prompted with hidden input if omitted)

Examples:

# Interactive login (prompts for server URL and token)
arcan login

# Non-interactive with token
arcan login --token arc_a1b2c3d4

# Full non-interactive
arcan login --server https://arcan.example.com --token arc_a1b2c3d4

Notes:

The login command tests the connection before saving.
Create a token first with arcan token create if you do not have one.

`arcan doctor`

Run local diagnostic checks on an Arcan installation without requiring a running server.

arcan doctor [flags]

Flags:

Flag	Default	Description
`--data-dir`	`~/.arcan/data`	Data directory to check

Checks performed:

Master key exists, is 32 bytes, has 0600 permissions
SQLite database opens, responds to ping, uses WAL mode
TLS CA certificate is valid and not expired
TLS server certificate is valid and not expired
Encryption round-trip (AES-256-GCM encrypt + decrypt)
Plugin directory scan

Examples:

# Check default installation
arcan doctor

# Check a custom data directory
arcan doctor --data-dir /var/arcan/data

Secrets (KV)

The KV engine manages static secrets with per-environment versioning. Commands accept aliases: arcan secret and arcan secrets work identically to arcan kv.

`arcan kv set`

Store a secret key-value pair. Creates or updates the secret.

arcan kv set <key> <value> [flags]

Flags:

Flag	Short	Default	Description
`--realm`	`-r`	`default`	Realm slug
`--env`	`-e`	`dev`	Environment (`dev`, `staging`, `prod`)

Examples:

# Store a database URL in the default realm
arcan kv set DATABASE_URL "postgres://user:pass@db:5432/app"

# Store in a specific realm and environment
arcan kv set API_KEY "sk_live_abc123" -r myapp -e prod

# Store in staging
arcan kv set REDIS_URL "redis://cache:6379" -r myapp -e staging

`arcan kv get`

Retrieve a secret value by key.

arcan kv get <key> [flags]

Flags:

Flag	Short	Default	Description
`--realm`	`-r`	`default`	Realm slug
`--env`	`-e`	`dev`	Environment (`dev`, `staging`, `prod`)

Examples:

# Get from default realm, dev environment
arcan kv get DATABASE_URL

# Get from a specific realm and environment
arcan kv get DATABASE_URL -r myapp -e prod

`arcan kv list`

List all secrets with metadata (key, environment, version, last updated). Aliases: arcan kv ls.

arcan kv list [flags]

Flags:

Flag	Short	Default	Description
`--realm`	`-r`	`default`	Realm slug
`--env`	`-e`		Filter by environment (shows all if omitted)

Examples:

# List all secrets in default realm
arcan kv list

# List secrets in a specific realm
arcan kv list -r myapp

# Filter by environment
arcan kv list -r myapp -e prod

`arcan kv delete`

Delete a secret by key. This permanently removes all versions.

arcan kv delete <key> [flags]

Flags:

Flag	Short	Default	Description
`--realm`	`-r`	`default`	Realm slug
`--env`	`-e`	`dev`	Environment (`dev`, `staging`, `prod`)

Examples:

# Delete from default realm
arcan kv delete TEMP_KEY

# Delete from a specific realm and environment
arcan kv delete OLD_SECRET -r myapp -e prod

`arcan kv export`

Export all secrets in an environment as dotenv or JSON format.

arcan kv export [flags]

Flags:

Flag	Short	Default	Description
`--realm`	`-r`	`default`	Realm slug
`--env`	`-e`	`dev`	Environment (`dev`, `staging`, `prod`)
`--format`		`env`	Output format: `env` or `json`

Examples:

# Export as dotenv (default)
arcan kv export -r myapp

# Export as JSON
arcan kv export -r myapp -e prod --format=json

# Pipe to a file
arcan kv export -r myapp -e prod > .env.prod

`arcan kv run`

Fetch all secrets from a realm/environment and inject them as environment variables into a child command.

arcan kv run [flags] -- <command> [args...]

Flags:

Flag	Short	Default	Description
`--realm`	`-r`	`default`	Realm slug
`--env`	`-e`	`dev`	Environment (`dev`, `staging`, `prod`)

Examples:

# Run a Node.js server with production secrets
arcan kv run -r myapp -e prod -- node server.js

# Run a Python app with dev secrets
arcan kv run -r myapp -- python manage.py runserver

# Run a shell script with default realm
arcan kv run -- ./start.sh

Notes:

Secrets are merged on top of your current environment variables.
The child process inherits stdin, stdout, and stderr.
Exit code from the child process is propagated.

`arcan kv encrypt`

Encrypt a plaintext value using the server's encryption key.

arcan kv encrypt [plaintext] [flags]

Flags:

Flag	Default	Description
`--stdin`	`false`	Read plaintext from stdin

Input modes:

Mode	Usage
Argument	`arcan kv encrypt "my-secret-value"`
Stdin pipe	`echo "value" \| arcan kv encrypt --stdin`
Interactive	`arcan kv encrypt` (prompts with hidden input)

Examples:

# Encrypt from argument
arcan kv encrypt "my-secret-value"

# Encrypt from stdin
echo "s3cr3t" | arcan kv encrypt --stdin

# Interactive (hidden input)
arcan kv encrypt

Output: The encrypted ciphertext (arcan:v1:...) printed to stdout.

`arcan apply`

Bulk-apply secrets from a YAML file. Creates or updates each secret.

arcan apply [flags]

Flags:

Flag	Short	Default	Description
`--file`	`-f`		YAML file with secrets to apply (required)
`--dry-run`		`false`	Print what would happen without making changes

YAML format:

realm: myapp
environment: prod
secrets:
  DATABASE_URL: "postgres://user:pass@db:5432/app"
  API_KEY: "sk_live_abc123"

Pre-encrypted values are passed through without re-encryption:

realm: myapp
environment: prod
secrets:
  DATABASE_URL:
    encrypted_value: "arcan:v1:abc123..."
  API_KEY: "plaintext-will-be-encrypted"

Examples:

# Apply secrets from a file
arcan apply -f secrets.yaml

# Preview changes without applying
arcan apply -f secrets.yaml --dry-run

Realms

Realms are security boundaries that isolate secrets, policies, and audit trails. Commands accept aliases: arcan realms works identically to arcan realm.

`arcan realm create`

Create a new realm with the given slug and display name.

arcan realm create <slug> <name>

Arguments:

slug -- 2-50 characters, lowercase alphanumeric with hyphens
name -- Human-readable display name

Examples:

arcan realm create my-app "My Application"
arcan realm create prod-api "Production API"

`arcan realm list`

List all realms. Aliases: arcan realm ls.

arcan realm list

Examples:

arcan realm list

`arcan realm delete`

Soft-delete a realm and all its contents. Prompts for confirmation.

arcan realm delete <slug>

Examples:

arcan realm delete my-app

Notes:

This cannot be undone.
You must be an admin of the realm to delete it.

Auth & Tokens

Commands accept aliases: arcan tokens works identically to arcan token.

`arcan token create`

Create a scoped API token for CLI or automation use.

arcan token create [flags]

Flags:

Flag	Default	Description
`--name`		Token name (required)
`--scopes`	`read`	Comma-separated scopes: `read`, `write`, `delete`

Scopes:

Scope	Permissions
`read`	Read secrets, list realms, view audit log
`write`	Create/update secrets, manage realms
`delete`	Delete secrets, revoke tokens

Examples:

# Read-only token for monitoring
arcan token create --name monitoring --scopes read

# CI/CD token
arcan token create --name ci-pipeline --scopes read,write

# Full access token
arcan token create --name admin-key --scopes read,write,delete

Notes:

The token value is shown only once. Save it immediately.
Configure the CLI with: arcan login --token <token>

`arcan token list`

List your API tokens. Aliases: arcan token ls.

arcan token list

Examples:

arcan token list

`arcan token revoke`

Revoke an API token by its ID. The token immediately stops working.

arcan token revoke <token-id>

Examples:

# Find the token ID first
arcan token list

# Revoke it
arcan token revoke abc12345-def6-7890-abcd-ef1234567890

SSO (Authentication Providers)

`arcan auth setup`

Interactive wizard to configure OIDC, SAML, or LDAP providers. Can also be run non-interactively with flags.

arcan auth setup [flags]

Flags:

Flag	Default	Description
`--type`		Provider type: `oidc`, `saml`, `ldap` (interactive if omitted)
`--name`		Provider name (e.g., `okta`, `google`, `azure`)
`--config`	`~/.arcan/config.yaml`	Config file path

OIDC flags:

Flag	Description
`--issuer`	OIDC issuer URL
`--client-id`	OIDC client ID
`--client-secret`	OIDC client secret
`--redirect-url`	OIDC redirect URL
`--allowed-domains`	Allowed email domains (comma-separated)

SAML flags:

Flag	Description
`--acs-url`	SAML Assertion Consumer Service URL
`--metadata-url`	SAML IdP metadata URL
`--metadata-file`	SAML IdP metadata file path

LDAP flags:

Flag	Description
`--ldap-url`	LDAP server URL (`ldaps://...`)
`--bind-dn`	LDAP bind DN
`--bind-password`	LDAP bind password
`--base-dn`	LDAP base DN for user search
`--user-filter`	LDAP user filter
`--required-group`	LDAP required group DN

Examples:

# Interactive wizard
arcan auth setup

# Non-interactive OIDC
arcan auth setup --type oidc --name okta \
  --issuer https://mycompany.okta.com \
  --client-id 0oa1b2c3d4e5f6 \
  --client-secret "$SECRET"

# Non-interactive SAML
arcan auth setup --type saml --name corporate \
  --acs-url https://arcan.example.com/api/v1/auth/saml/corporate/acs \
  --metadata-url https://idp.example.com/saml/metadata

# Non-interactive LDAP
arcan auth setup --type ldap --name active-directory \
  --ldap-url ldaps://ldap.example.com:636 \
  --bind-dn "cn=arcan,ou=services,dc=example,dc=com" \
  --bind-password "$BIND_PW" \
  --base-dn "ou=users,dc=example,dc=com"

`arcan auth test`

Test connectivity to a configured SSO provider.

arcan auth test <provider-name>

Examples:

arcan auth test okta
arcan auth test active-directory

`arcan auth update-presets`

Refresh the built-in SSO provider presets from the latest defaults.

arcan auth update-presets

Examples:

arcan auth update-presets

Policy (RBAC)

`arcan policy roles`

List all available roles and their capabilities.

arcan policy roles

Examples:

arcan policy roles

`arcan policy bind`

Assign a role to a user within a realm.

arcan policy bind [flags]

Flags:

Flag	Short	Default	Description
`--realm`	`-r`	`default`	Realm slug
`--user-id`			User ID to bind (required)
`--role`			Role to assign: `admin`, `member`, `viewer` (required)

Examples:

arcan policy bind -r myapp --user-id abc123 --role member
arcan policy bind -r prod --user-id abc123 --role admin

`arcan policy unbind`

Remove a user's role binding from a realm.

arcan policy unbind [flags]

Flags:

Flag	Short	Default	Description
`--realm`	`-r`	`default`	Realm slug
`--user-id`			User ID to unbind (required)

Examples:

arcan policy unbind -r myapp --user-id abc123

`arcan policy list`

List role bindings in a realm. Aliases: arcan policy ls.

arcan policy list [flags]

Flags:

Flag	Short	Default	Description
`--realm`	`-r`	`default`	Realm slug

Examples:

arcan policy list -r myapp
arcan policy list -r prod

Operations

`arcan audit list`

Query the audit log for security and operational events.

arcan audit list [flags]

Flags:

Flag	Default	Description
`--realm`		Filter by realm slug
`--type`		Filter by event type (e.g., `secret.set`, `auth.login`)
`--actor`		Filter by actor (email or user ID)
`--limit`	`50`	Maximum events to return

Examples:

# List recent audit events
arcan audit list

# Filter by realm
arcan audit list --realm myapp --limit 20

# Filter by event type
arcan audit list --type secret.set

# Filter by actor
arcan audit list --actor [email protected]

`arcan master-key verify`

Validate the master encryption key by performing an encrypt/decrypt round-trip test.

arcan master-key verify [flags]

Flags:

Flag	Default	Description
`--data-dir`	`~/.arcan/data`	Data directory containing `master.key`

Examples:

arcan master-key verify
arcan master-key verify --data-dir /var/arcan/data

`arcan master-key generate`

Generate a new 32-byte master encryption key.

arcan master-key generate [flags]

Flags:

Flag	Default	Description
`--data-dir`	`~/.arcan/data`	Data directory to write `master.key`
`--force`	`false`	Overwrite existing key file

Examples:

# Generate a new master key (fails if one exists)
arcan master-key generate

# Force overwrite an existing key
arcan master-key generate --force

Notes:

The key is written with 0600 permissions.
Overwriting a master key makes all previously encrypted secrets unrecoverable.

Plugins

`arcan plugin init`

Scaffold a new engine plugin project with go.mod, main.go, Makefile, and README.md.

arcan plugin init [flags]

Flags:

Flag	Default	Description
`--name`		Plugin name in kebab-case (interactive if omitted)
`--display-name`		Human-readable display name
`--description`		Plugin description
`--capabilities`		Comma-separated capabilities

Available capabilities:

secret_generation
secret_validation
dynamic_credentials
root_rotation
crypto
certificates

Examples:

# Interactive mode
arcan plugin init

# Non-interactive
arcan plugin init --name my-identity \
  --capabilities secret_generation,dynamic_credentials

Output: Creates arcan-plugin-<name>/ directory with all scaffolding files.

`arcan plugin list`

List all registered engines (built-in and plugin) from the running server.

arcan plugin list

Examples:

arcan plugin list

`arcan plugin remove`

Remove a plugin binary from the local plugins directory.

arcan plugin remove <name> [flags]

Flags:

Flag	Default	Description
`--data-dir`	`~/.arcan/data`	Data directory containing `plugins/`

Examples:

arcan plugin remove my-identity

Notes:

Built-in engines (e.g., totp) cannot be removed.
Prompts for confirmation before deleting.
The server must be restarted for the change to take effect.

Global Flags​

Server & Setup​

arcan server​

arcan login​

arcan doctor​

Secrets (KV)​

arcan kv set​

arcan kv get​

arcan kv list​

arcan kv delete​

arcan kv export​

arcan kv run​

arcan kv encrypt​

arcan apply​

Realms​

arcan realm create​

arcan realm list​

arcan realm delete​

Auth & Tokens​

arcan token create​

arcan token list​

arcan token revoke​

SSO (Authentication Providers)​

arcan auth setup​

arcan auth test​

arcan auth update-presets​

Policy (RBAC)​

arcan policy roles​

arcan policy bind​

arcan policy unbind​

arcan policy list​

Operations​

arcan audit list​

arcan master-key verify​

arcan master-key generate​

Plugins​

arcan plugin init​

arcan plugin list​

arcan plugin remove​

Global Flags

Server & Setup

`arcan server`

`arcan login`

`arcan doctor`

Secrets (KV)

`arcan kv set`

`arcan kv get`

`arcan kv list`

`arcan kv delete`

`arcan kv export`

`arcan kv run`

`arcan kv encrypt`

`arcan apply`

Realms

`arcan realm create`

`arcan realm list`

`arcan realm delete`

Auth & Tokens

`arcan token create`

`arcan token list`

`arcan token revoke`

SSO (Authentication Providers)

`arcan auth setup`

`arcan auth test`

`arcan auth update-presets`

Policy (RBAC)

`arcan policy roles`

`arcan policy bind`

`arcan policy unbind`

`arcan policy list`

Operations

`arcan audit list`

`arcan master-key verify`

`arcan master-key generate`

Plugins

`arcan plugin init`

`arcan plugin list`

`arcan plugin remove`