Skip to content

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

janus-client [--socket PATH] <command> [flags]

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.