CLI reference (appctl)¶
Auto-generated from
crates/cli/src/main.rs(the clap derive). Runscripts/docs/regen.pyto 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¶
- Error reference — exit codes and how schedulers should branch on them
- Scheduler integration cookbook — Control-M, AutoSys, $Universe, TWS recipes
- Permissions — which permission level each command requires