apus logs
Tail Gateway file logs over RPC. Works in remote mode.
Options
--limit <n>: max log lines to return (default200)--max-bytes <n>: max bytes to read from the log file (default250000)--follow: follow the log stream--interval <ms>: polling interval while following (default1000)--json: emit line-delimited JSON events--plain: plain text output without styled formatting--no-color: disable ANSI colors--local-time: render timestamps in your local timezone (default)--utc: render timestamps in UTC
Polling intervals larger than 2,147,000,000 ms are capped at that value to avoid timer overflow.
Shared Gateway RPC options
--url <url>: Gateway WebSocket URL--port <port>: select a local Gateway port, overriding the configured remote URL andAPUS_GATEWAY_URL; cannot be combined with--url--token <token>: Gateway token--timeout <ms>: timeout in ms (default30000)--expect-final: wait for a final response when the Gateway call is agent-backed
Passing --url skips auto-applied config credentials; include --token explicitly if the target Gateway requires auth.
--port requires an integer from 1 to 65535; empty or whitespace-only values are invalid. Omit the option to use the configured or environment target.
Examples
apus logs
apus logs --follow
apus --dev logs --follow
apus --profile work logs --follow
apus logs --follow --interval 2000
apus logs --limit 500 --max-bytes 500000
apus logs --json
apus logs --plain
apus logs --no-color
apus logs --utc
apus logs --follow --local-time
apus logs --port 19083 --json
apus logs --url ws://127.0.0.1:18789 --token "$APUS_GATEWAY_TOKEN"
The selected root profile matches the Gateway's rolling file: the default
profile uses apus-YYYY-MM-DD.log, while named profiles use
apus-<profile>-YYYY-MM-DD.log (for example,
apus-dev-YYYY-MM-DD.log).
Fallback and recovery behavior
- If local configuration cannot be read or parsed,
apus logsreads local file logs and warns withapus doctor --fixguidance. This recovery also works with--follow; explicit URL targets retain their authentication requirements. - If the implicit local loopback Gateway asks for pairing, closes during connect, or times out before
logs.tailanswers,apus logsfalls back to the configured Gateway file log automatically. Explicit--urltargets never use this fallback. --followdoes not fall back to that configured file after an implicit local Gateway RPC failure — a stale side-by-side file could mislead a live tail. On Linux it instead uses the active user-systemd Gateway journal by PID when available (prints the selected source); otherwise it keeps retrying the live Gateway.- During
--follow, transient disconnects (WebSocket close, timeout, connection drop) trigger automatic reconnection with exponential backoff: up to 8 retries, capped at 30s between attempts. A warning prints to stderr on each retry, and a[logs] gateway reconnectednotice prints once a poll succeeds. In--jsonmode both are emitted as{"type":"notice"}records on stderr. Authentication and invalid target errors still exit immediately. - In
--follow --jsonmode, log-source transitions are emitted as{"type":"meta"}records. Track cursors persourceKind: a stream can move from Gateway file output (sourceKind: "file") to local journal fallback (sourceKind: "journal",localFallback: true, withservice.pid/service.unit) and back to Gateway file output after recovery. Do not assume one stable source or cursor for the whole session, and tolerate overlapping lines when recovery replays the Gateway file cursor.
In --json mode, invalid --port, --limit, --interval, or --max-bytes values and conflicting --url/--port options produce the standard CLI failure envelope on stdout: {"ok":false,"error":{"type":"cli_error","message":"..."}}. Terminal log-fetch failures instead emit {"type":"error",...} on stderr. Both exit with status 1.
In text mode, terminal log-fetch failures print the redacted error reason, selected Gateway connection details, and a doctor hint on stderr. A received RPC rejection is shown as the error, rather than reported as a Gateway reachability failure.
In JSON mode, terminal log-fetch errors use the same redacted failure reason for message and error, including RPC rejections, timeouts, disconnects, and invalid response payloads. The record retains connection details and a doctor hint on stderr; the command still exits with status 1.