> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# nodes

# `wednesdayai nodes`

Manage paired nodes (devices) and invoke node capabilities.

Related:

* Nodes overview: [Nodes](https://docs.wednesdayai.dev/next/users/nodes)
* Camera: [Camera nodes](https://docs.wednesdayai.dev/next/users/nodes/camera.md)
* Images: [Image nodes](https://docs.wednesdayai.dev/next/users/nodes/images.md)

Common options:

* `--url`, `--token`, `--timeout`, `--json`

## Common commands

```bash theme={"dark"}
wednesdayai nodes list
wednesdayai nodes list --connected
wednesdayai nodes list --last-connected 24h
wednesdayai nodes pending
wednesdayai nodes approve <requestId>
wednesdayai nodes status
wednesdayai nodes status --connected
wednesdayai nodes status --last-connected 24h
```

`nodes list` prints pending/paired tables. Paired rows include the most recent connect age (Last Connect).
Use `--connected` to only show currently-connected nodes. Use `--last-connected <duration>` to
filter to nodes that connected within a duration (e.g. `24h`, `7d`).

`nodes status` adds `Registered` (first registration age) and `Last Active` columns for paired
nodes. A paired node with no activity for longer than `gateway.devices.staleAfterDays` (default 90)
shows `stale` in its Status cell; a connected node is never stale. Archive stale records with
[`devices prune --stale`](https://docs.wednesdayai.dev/next/users/cli/devices#openclaw-devices-prune).

Pairing changes go through the gateway RPC when a gateway is running. When no gateway owns
storage, `nodes pending`, `nodes approve`, `nodes reject` and `nodes rename` open the session
database locally and apply the change directly. `nodes status` and the invoke/run commands always
need a running gateway. Legacy `nodes/*.json` files are imported into the database on first open
(see [Gateway pairing storage](https://docs.wednesdayai.dev/next/admin/gateway/pairing.md#storage)).

## Invoke / run

```bash theme={"dark"}
wednesdayai nodes invoke --node <id|name|ip> --command <command> --params <json>
wednesdayai nodes run --node <id|name|ip> <command...>
wednesdayai nodes run --raw "git status"
wednesdayai nodes run --agent main --node <id|name|ip> --raw "git status"
```

Invoke flags:

* `--params <json>`: JSON object string (default `{}`).
* `--invoke-timeout <ms>`: node invoke timeout (default `15000`).
* `--idempotency-key <key>`: optional idempotency key.

### Exec-style defaults

`nodes run` mirrors the model’s exec behavior (defaults + approvals):

* Reads `tools.exec.*` (plus `agents.list[].tools.exec.*` overrides).
* Uses exec approvals (`exec.approval.request`) before invoking `system.run`.
* `--node` can be omitted when `tools.exec.node` is set.
* Requires a node that advertises `system.run` (macOS companion app or headless node host).

Flags:

* `--cwd <path>`: working directory.
* `--env <key=val>`: env override (repeatable). Note: node hosts ignore `PATH` overrides (and `tools.exec.pathPrepend` is not applied to node hosts).
* `--command-timeout <ms>`: command timeout.
* `--invoke-timeout <ms>`: node invoke timeout (default `30000`).
* `--needs-screen-recording`: require screen recording permission.
* `--raw <command>`: run a shell string (`/bin/sh -lc` or `cmd.exe /c`).
  In allowlist mode on Windows node hosts, `cmd.exe /c` shell-wrapper runs require approval
  (allowlist entry alone does not auto-allow the wrapper form).
* `--agent <id>`: agent-scoped approvals/allowlists (defaults to configured agent).
* `--ask <off|on-miss|always>`, `--security <deny|allowlist|full>`: overrides.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.