Command-line interface¶
JANUS ships command-line tools alongside its services. Every one of them is a first-class surface: the actions an operator performs from a terminal are the same Management API calls the WebUI makes, subject to the same authorization and audit.
The tools¶
| Binary | Role |
|---|---|
janus |
Operator CLI. Enrollment triage (list, inspect, approve, reject, revoke) from a terminal. |
controller |
Controller process and host-local administration (run, config, admin). |
janus-gateway |
Gateway node: data-plane agent, outbound enrollment and liveness. |
janus-client |
JANUS Client command-line interface (a client of the local daemon). |
janus-clientd |
JANUS Client background runtime (Linux only). |
janus-site-edge |
Site Edge product binary: identity, enrollment and local lifecycle. |
The CLI holds no privileged shortcut
janus is a thin API client. It holds no privileged channel to Git,
PostgreSQL or a gateway. It exists so an operator can perform enrollment
triage without a browser.
janus — operator CLI¶
A thin Management API client authenticated with a bearer token.
Synopsis¶
janus enrollment list [--state pending|approved|rejected|revoked]
janus enrollment show <gateway-id>
janus enrollment approve <gateway-id>
janus enrollment reject <gateway-id> --reason TEXT
janus enrollment revoke <gateway-id> --reason TEXT
janus version
Global flags¶
| Flag | Environment | Meaning |
|---|---|---|
--controller URL |
JANUS_CONTROLLER_URL |
Controller base URL. Required. |
--token TOKEN |
JANUS_TOKEN |
API bearer token. Required. |
A flag may appear before or after the positional gateway id; both orderings are accepted.
Subcommands¶
| Subcommand | Result |
|---|---|
enrollment list |
Table of enrollment records: gateway id, state, hostname, fingerprint. --state filters the list. |
enrollment show <gateway-id> |
Full record: fingerprint, state and trust, hostname, source address, version, capabilities, request/decision timestamps, reason and last seen. |
enrollment approve <gateway-id> |
Approves the record and prints the new state. |
enrollment reject <gateway-id> --reason TEXT |
Rejects the record. --reason is required. |
enrollment revoke <gateway-id> --reason TEXT |
Revokes the record. --reason is required. |
Examples¶
export JANUS_CONTROLLER_URL=https://janus.example
export JANUS_TOKEN=<your-token>
janus enrollment list --state pending
janus enrollment show gw-7f3a
janus enrollment approve gw-7f3a
janus enrollment revoke gw-7f3a --reason "decommissioned"
controller — controller administration¶
Synopsis¶
controller run [flags]
controller config validate [flags]
controller config compile [flags]
controller config migrate [flags]
controller config migrate-references [flags]
controller admin <subcommand> [flags]
controller run¶
Starts the controller process.
| Flag | Environment | Meaning |
|---|---|---|
--config PATH |
JANUS_CONTROLLER_CONFIG |
Controller configuration file. |
--db-password |
JANUS_DB_PASSWORD |
PostgreSQL password. |
The database URL is taken from JANUS_DATABASE_URL when set, otherwise derived
from the configuration. The Management API listener is taken from the
configuration (managementApi.listen) and honoured verbatim; an invalid address
fails the start rather than falling back to a wildcard or to loopback.
controller config validate¶
Validates a desired-state directory.
| Flag | Default | Meaning |
|---|---|---|
--path |
. |
Configuration directory. |
--config |
— | Controller configuration file. |
Prints OK: configuration is valid on success; otherwise prints the validation
report and exits non-zero.
controller config compile¶
Compiles the desired state for one gateway and prints the compiled gateway desired state as JSON.
| Flag | Default | Meaning |
|---|---|---|
--path |
. |
Configuration directory. |
--gateway |
— | Required. Gateway name to compile for. |
--revision |
unknown |
Git revision identifier recorded in the output. |
--config |
— | Controller configuration file. |
The configuration is validated first; an invalid configuration is refused before compilation.
controller config migrate¶
Migrates a desired-state repository to the canonical apiVersion.
controller config migrate-references¶
Pins legacy name-only tenant references to durable identity. The relationships
MSP → Tenant, Deployment → Tenant and GatewayNode → Tenant are identity-bearing:
the tenant's immutable UUID is authoritative and the human-readable name is
advisory display metadata. This command upgrades desired state that still carries
the older name-only form by resolving each name ONCE to the tenant's UUID and
rewriting the reference as {uuid, name} — the advisory name is kept for
readable Git.
It is a pure working-tree transformation: it never commits, pushes or talks to a
controller. It fails closed — a name that does not resolve to a declared tenant
is reported and left untouched rather than guessed. After it runs, a rename
preserves the relationship, a deletion makes the reference dangling (fail closed)
and a reused name cannot re-point it. Flags: --path DIR, --check (read-only;
non-zero if legacy references remain), --dry-run (propose changes).
controller admin — host-local administration¶
Everything under admin is reachable only from the controller host. There is
no network endpoint that can bootstrap an administrator, enable break-glass, or
rotate the recovery credential. Passwords are read from a hardened file or from
stdin — never from an argument, so they cannot enter the process list or a
shell history.
| Subcommand | Purpose |
|---|---|
bootstrap |
Create the first platform administrator. |
create-token |
Issue an API token for a principal. |
status |
Show bootstrap and break-glass state. |
enable-break-glass |
Enable the local recovery principal for a bounded time. |
disable-break-glass |
Disable the local recovery principal. |
rotate-break-glass |
Rotate the recovery credential. |
bootstrap flags:
| Flag | Meaning |
|---|---|
--username |
Required. Username locator for the first administrator. |
--password-file |
Read the password from a file satisfying the secret-material invariants. |
--password-stdin |
Read the password from stdin. |
--replace |
Replace an existing administrator set (a separately audited recovery operation). |
--config |
Controller configuration file. |
create-token flags: --username (required), --name (default host-local),
--scopes (comma-separated; empty means the principal's full authorization),
--ttl (default 24h). The token is shown once.
enable-break-glass requires --duration (hard maximum 4h) and --reason
(recorded in the high-severity audit trail); it accepts --password-file or
--password-stdin to set the recovery credential on first use.
# Password from a file, never from the command line.
controller admin bootstrap --username admin --password-file /root/admin.pw
controller admin create-token --username admin --name ci --ttl 168h
controller admin enable-break-glass --duration 1h --reason "controller recovery"
janus-gateway — gateway node¶
Synopsis¶
janus-gateway run [--config PATH]
janus-gateway enroll [--config PATH] [--controller URL] [--wait]
janus-gateway status [--config PATH] [--controller URL]
janus-gateway version
The gateway identity is an Ed25519 keypair stored 0600 in the configured state
directory. It is created on first use and never leaves the host; it is
independent of the host name or address, so re-addressing or renaming a gateway
never creates a second trusted identity.
janus-gateway enroll¶
| Flag | Default | Meaning |
|---|---|---|
--config PATH |
JANUS_GATEWAY_CONFIG, else /etc/janus/gateway.yaml |
Configuration file. |
--controller URL |
JANUS_CONTROLLER_URL, else controller.url |
Controller base URL. |
--identity PATH |
configured identity file | Gateway identity file. |
--hostname |
OS hostname | Reported node label. |
--wait |
false | Wait until the enrollment is approved or rejected. |
--timeout |
10m |
How long --wait polls before giving up. |
On success it prints the gateway id, fingerprint and state, and states that an
administrator must approve the fingerprint before the gateway is trusted. With
--wait it polls and reports approval, rejection or revocation.
janus-gateway status¶
Prints the gateway id and fingerprint, then the enrollment state and trust
(not approved when there is no approved record).
janus-gateway run¶
Runs the data-plane agent. The apply-helper path selects whether the agent applies compiled desired state to the kernel; when it is empty the agent is delivery/validation only and never touches the kernel. When a controller is configured, a liveness heartbeat runs alongside — a controller outage never stops already-applied state.
janus-client — client CLI¶
janus-client is an IPC client of janus-clientd. It holds no privilege, opens
no WireGuard interface, reads no private key and contains no failover logic.
Synopsis¶
Commands¶
| Command | Purpose |
|---|---|
status |
Show the client's current state. |
version |
Show the client and protocol versions. |
capabilities |
Show what this client and host can do. |
diagnostics |
Show a detailed diagnostics report. |
support-bundle |
Write a redacted support archive. |
help |
Show help. |
Flags¶
| Flag | Default | Meaning |
|---|---|---|
--socket PATH |
/run/janus-client/client.sock |
Local management socket. |
--json |
off | Machine-readable JSON output. |
--timeout DUR |
10s |
Request timeout. |
--out PATH |
janus-client-support-<timestamp>.tar.gz |
Output path, support-bundle only. |
Flags may appear before or after the command; both orderings are valid.
status output¶
Prints whether the client is provisioned, its state (and a fixed reason when it
is not provisioned), the interface, the active and preferred gateways, the
device (deployment/device), its addresses and AllowedIPs, whether automatic
failover is on, a table of eligible gateways (with reachability and handshake
age), and the last failover transition.
Reachability of a gateway that is not the active peer is reported as unknown,
never as unreachable.
Example¶
janus-client status
janus-client status --json
janus-client diagnostics
janus-client support-bundle --out /tmp/janus-support.tar.gz
janus-clientd — client daemon¶
janus-clientd is Linux only and requires exactly one privilege:
CAP_NET_ADMIN, to program a WireGuard interface. It is the only component that
owns active client runtime state. It keeps running and answering management
queries when no device is provisioned, so a bare installation can say why it is
not connected instead of restart-looping.
| Flag | Default | Meaning |
|---|---|---|
-manifest |
/etc/janus-client/manifest.json |
Client manifest JSON. |
-key-file |
/etc/janus-client/private.key |
Client-owned WireGuard private key (0600). |
-interface |
janus0 |
WireGuard interface to manage. |
-handshake-max-age |
3m |
How old a handshake may be before the active gateway is considered unreachable. |
-socket |
/run/janus-client/client.sock |
Local management socket. |
-log-level |
info |
debug, info, warn or error. |
There is no config file: provisioning is the two input files above. See Client.
janus-site-edge — Site Edge CLI¶
Synopsis¶
janus-site-edge version
janus-site-edge identity [-config PATH]
janus-site-edge status [-config PATH] [-json]
janus-site-edge config [-config PATH] -controller URL [-ca FILE]
janus-site-edge enroll [-config PATH] -deployment D -site S -edge-name N [-controller URL] [-ca FILE]
janus-site-edge leave [-config PATH] [-purge-identity]
janus-site-edge diagnostics [-config PATH]
janus-site-edge run [-config PATH]
| Command | Result |
|---|---|
identity |
Edge id, public key, fingerprint and installation id. The public key is copied into the controller when creating the Site Edge; the private key never leaves the host. |
status |
Enrollment state, controller, binding, last contact and version. -json emits machine-readable output. |
config |
Record the controller URL and/or CA. |
enroll |
Enroll outbound with a (deployment, site, edge-name) binding. |
leave |
Release the binding locally; -purge-identity destroys the local key material. |
diagnostics |
A diagnostics report. |
run |
Run the edge service. |
Exit codes and machine-readable output¶
janus-client uses a fixed, documented exit-code contract:
| Code | Meaning |
|---|---|
0 |
success |
1 |
generic failure |
2 |
usage error |
3 |
service unavailable |
4 |
not enrolled |
5 |
enrollment failed |
6 |
controller unreachable |
7 |
device revoked |
8 |
permission denied |
9 |
unsupported capability or version mismatch |
--json on janus-client selects machine-readable output for every command.
janus-site-edge status -json emits JSON. The other tools print human-readable
text and report failure through a non-zero process exit; they do not define a
numbered exit-code contract.
Related¶
- API — the surface these tools call
- Controller installation
- Gateway installation
- Client — the client runtime and its provisioning files