Skip to content

CLI reference (appctl)

Auto-generated from crates/cli/src/main.rs (the clap derive). Run scripts/docs/regen.py to refresh.

The appctl binary is the integration point for schedulers (Control-M, AutoSys, $Universe, TWS, Airflow) and on-call operators. It calls the same REST API as the web UI and returns deterministic exit codes — see the Error reference for the full mapping.

Global options

Argument Required Default Env Description
--url no http://localhost:8080 APPCONTROL_URL Backend URL
--api-key no — APPCONTROL_API_KEY API key

Commands

start

Start an application

Argument Required Default Env Description
<APP> yes — — Application name or ID
--wait no false — Wait for all components to reach RUNNING
--timeout no 300 — Timeout in seconds (with --wait)
--dry-run no false — Dry run (show plan without executing)

stop

Stop an application

Argument Required Default Env Description
<APP> yes — — (undocumented)
--wait no false — (undocumented)
--timeout no 300 — (undocumented)

status

Show application status

Argument Required Default Env Description
<APP> yes — — (undocumented)
--format no table — (undocumented)

switchover

DR site switchover

Argument Required Default Env Description
<APP> yes — — (undocumented)
--target-site yes — — (undocumented)
--mode no FULL — (undocumented)
--wait no false — (undocumented)

diagnose

Run 3-level diagnostic

Argument Required Default Env Description
<APP> yes — — (undocumented)
--format no table — (undocumented)

rebuild

Rebuild application components

Argument Required Default Env Description
<APP> yes — — (undocumented)
--components no — — (undocumented)
--dry-run no false — (undocumented)
--wait no false — (undocumented)

pki

PKI and enrollment management

(no arguments)

pki init

Initialize the CA for this organization (one-time setup)

Argument Required Default Env Description
--org-name yes — — Organization name for the CA
--validity-days no 3650 — CA validity in days (default 3650 = 10 years)
--out no — — Output directory for CA files (optional — also stored in backend DB)

pki create-token

Create an enrollment token for agents/gateways

Argument Required Default Env Description
--name yes — — Human-readable name for this token
--max-uses no — — Max number of uses (default: unlimited)
--valid-hours no 24 — Validity in hours (default 24)
--scope no agent — Token scope: "agent" or "gateway" (default "agent")

pki list-tokens

List enrollment tokens

(no arguments)

pki revoke-token

Revoke an enrollment token

Argument Required Default Env Description
<ID> yes — — Token ID to revoke

pki issue-agent

Issue an agent certificate locally (requires CA key)

Argument Required Default Env Description
--hostname yes — — Agent hostname
--ca-cert yes — — Path to CA cert PEM
--ca-key yes — — Path to CA key PEM
--out no . — Output directory for agent cert files
--validity-days no 365 — Validity in days (default 365)

pki issue-gateway

Issue a gateway certificate locally (requires CA key)

Argument Required Default Env Description
--cn yes — — Gateway hostname / CN
--san-dns yes — — Additional DNS SANs
--san-ip yes — — Additional IP SANs
--ca-cert yes — — Path to CA cert PEM
--ca-key yes — — Path to CA key PEM
--out no . — Output directory
--validity-days no 365 — Validity in days (default 365)

pki events

Show enrollment events (audit trail)

(no arguments)

Examples

# Start an application and wait up to 10 minutes for it to be RUNNING
appctl --url https://appcontrol.example.com \
       --api-key $APPCONTROL_API_KEY \
       start core-banking --wait --timeout 600

# Check status as JSON (suitable for parsing in a script)
appctl status core-banking --format json | jq '.components[] | select(.state != "RUNNING")'

# Dry-run a switchover to validate the plan without executing
appctl switchover core-banking --target-site lyon --mode PROGRESSIVE

# PKI: initialise the CA and create a 24-hour enrolment token for two agents
appctl pki init --org-name 'ACME Bank' --validity-days 3650 --out ./ca
appctl pki create-token --name 'paris-batch-fleet' --max-uses 2 --valid-hours 24

See also