apus nodes

Manage paired nodes (devices) and invoke node capabilities.

Related: Nodes overview - Active computer presence - Camera nodes - Image nodes

Common options on every subcommand: --url <url>, --token <token>, --timeout <ms> (default varies by command), --json.

For numeric options such as --location-timeout, --max-age, and --quality, omit the flag to use its default. An explicit empty or whitespace-only value is invalid and fails before node lookup or Gateway requests.

Status

apus nodes status
apus nodes status --connected
apus nodes status --last-connected 24h
apus nodes list
apus nodes describe --node <idOrNameOrIp>

status and list both accept --connected (only connected nodes) and --last-connected <duration> (for example 24h or 7d, matching only nodes that connected within the duration). Both use the Gateway's recorded last connection time, including recent reconnects and disconnected nodes with known connection history. list shows pending and paired nodes in separate tables. Paired rows carry the most recent connect age (Last Connect). status shows one merged table with per-node capability, version, and last-input detail. A connected macOS node reports activity from interaction with Apus without extra permissions. Optional System-wide presence detection also reports physical activity in other apps and requires Accessibility. The freshest row is marked active. See Active computer presence. describe prints one node's capabilities, permissions, activity, and effective/pending invoke commands.

When host stats are available, status includes a detail fragment such as load 3.2/24 · mem 151/192 GB · disk 1.2 TB free. describe shows the same summary in its Stats row. Load is the 1-minute average followed by CPU count, memory is used/total, and byte values use binary scaling with GB/TB labels. Unavailable load or disk readings are omitted. Offline nodes show the saved snapshot with an age such as (last known 27d ago), measured from the snapshot's original timestamp. See Node host stats.

--node accepts an exact ID, IP address, display name, or ID prefix of at least six characters. Exact ID and IP matches take precedence over names and prefixes. Within the strongest match, connected nodes take precedence. If clients share a name, use an exact ID to disambiguate. Client type does not choose the target.

Pairing

apus nodes pending
apus nodes approve <requestId>
apus nodes reject <requestId>
apus nodes remove --node <id|name|ip>
apus nodes rename --node <id|name|ip> --name <displayName>

These commands manage the node's approved command/capability surface on its paired-device record. Device pairing (apus devices approve) gates the node's WebSocket connect handshake.

For manual enrollment, first approve the device request, then restart or rerun a node paused on PAIRING_REQUIRED. Its reconnect creates the separate request shown by nodes pending. Approve that node request, whose ID differs from the device request ID. See Node pairing and status for the complete sequence.

Invoke

apus nodes invoke --node <id> --command system.which --params '{"bins":["uname"]}'

Flags:

The invocation timeout covers Gateway checks, node wake-up, readiness retries, and the node response. Clock adjustments do not reset or extend this elapsed-time budget.

system.run and system.run.prepare are blocked here. Use the exec tool with host=node for shell execution instead. system.which is allowed through invoke.

Notify, push, location, screen

apus nodes notify --node <id> --title "Build" --body "Done" --priority timeSensitive
apus nodes push --node <id> --title "Apus" --environment sandbox
apus nodes location get --node <id> --accuracy precise
apus nodes screen record --node <id> --duration 10s --fps 10 --out ./clip.mp4

Camera and macOS widget-panel commands have their own docs: Camera nodes, Widget panel. The bundled experimental Canvas plugin registers apus nodes canvas with the surviving present, hide, and navigate subcommands.

Related