# IdentityMD worker daemon CLI reference

**Reviewed:** 2026-10-16  
**Scope:** the `imd` CLI in the official [IdentityMD worker distribution](https://github.com/Identity-md/worker), specifically the committed CLI at [`dbdcf99` (`dist/cli.js`)](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js). Its built-in help identifies itself as daemon `v0.1.2+63e0a393`. The official [README](https://github.com/Identity-md/worker/blob/main/README.md) describes the supported worker workflows.

This reference is for the worker seat operator. “No options” means the command has no documented, meaningful command-specific flags; the root CLI parser accepts global help (`-h`, `--help`). Unknown flags may be ignored by some commands, so that permissive parser behavior should not be read as support for those flags. Values in angle brackets are arguments to supply, not literal text.

## Seat setup, identity, and work

| Command | Options / arguments | Purpose and notes |
|---|---|---|
| `imd help` (or invoke with no command to print help; `-h` / `--help` after a command prints help) | `-h`, `--help` | Print the command overview and root options. Invoking with no command also prints the overview (with a nonzero exit status). [CLI help and dispatcher](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js) |
| `imd pair` | `--server <url>` | Pair this device with the wallet that owns an eligible IdentityMD NFT. If the token is not registered as an ERC-8004 agent, the pairing flow points the wallet holder to the registration page. The default server is the configured server or `https://api.imd.fun`. [README: start and pair](https://github.com/Identity-md/worker/blob/main/README.md#start-and-pair), [pair implementation](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js) |
| `imd start` | `--server <url>`; `--concurrency <1-4>`; `--runtime claude|codex`; `--auto-update` | Connect this machine and accept assigned jobs. It performs pairing first when needed (interactive terminal required for that path), selects the requested runtime or its detected default, and persists the concurrency setting. The daemon runs in the foreground. Automatic update supervises the worker and restarts it after a successful update. [README: start and pair](https://github.com/Identity-md/worker/blob/main/README.md#start-and-pair), [README: updates](https://github.com/Identity-md/worker/blob/main/README.md#updates), [CLI help and start implementation](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js) |
| `imd status` | None | Show local config state, device key, paired token ID, capacity, runtime detection, and server eligibility when reachable. [status implementation](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js) |
| `imd doctor` | `--runtime claude|codex` | Run local readiness checks (including Git, Foundry, configured tools, runtime execution, sandbox and network checks when applicable) and ask the control plane why the device is or is not being offered work. [CLI help and doctor implementation](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js) |
| `imd unlink` | None | Revoke this device's server-side binding so the NFT can authorize another device. The device key remains locally; start/pair again to reconnect. [unlink implementation](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js) |
| `imd whoami` | None | Print this machine's device key identifier. This is the public device identity string, not an export of the private key. [whoami implementation](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js) |
| `imd update` | None | Update a release installation or update a source checkout using the update mechanism available to that installation. [README: updates](https://github.com/Identity-md/worker/blob/main/README.md#updates), [update implementation](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js) |
| `imd sandbox` (alias: `imd jail-setup`) | None | Set up the host sandbox prerequisites used by jailed jobs on Linux. The help says this may install `bubblewrap` and `socat` and may require root. [CLI help and sandbox implementation](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js) |

`imd start` is the command that receives and runs assigned jobs. The README describes the daemon's runtime choices, concurrent task limit, job readiness checks, and outbox persistence. It does not expose a general-purpose “run job by ID” command in this CLI. [README](https://github.com/Identity-md/worker/blob/main/README.md#start-and-pair), [CLI dispatcher](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js)

## Background service

| Command | Options / arguments | Purpose |
|---|---|---|
| `imd service install` | `--runtime claude|codex`; `--concurrency <1-4>`; `--auto-update`; `--boot` | Install and start the background worker, configuring autostart. On Linux, `--boot` enables lingering for logout/reboot persistence; macOS and Windows start at user login. Pair and sign in to a runtime first. |
| `imd service restart` | `--runtime claude|codex` | Restart the service, optionally switching the saved runtime. |
| `imd service status` | None | Show service state. |
| `imd service logs` | `--follow` or `-f` | Show service logs; follow streams them. Ctrl+C exits the viewer, not the worker. |
| `imd service start` | None | Start the installed service. |
| `imd service stop` | None | Stop it until its next autostart event or explicit start. |
| `imd service uninstall` | None | Remove service autostart configuration. |

Service-only flags are rejected on actions where they do not apply; for example `--follow` is only for `logs`, and `--runtime` is the only mutable option on `restart`. `-h` / `--help` prints service usage. [README: background service](https://github.com/Identity-md/worker/blob/main/README.md#background-service), [service usage and parser](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js)

## Skills, tools, and RPC configuration

| Command | Options / arguments | Purpose |
|---|---|---|
| `imd skills` or `imd skills list` | None | List network-offered skills and which are enabled locally. |
| `imd skills add <id>` | `<id>` | Enable a skill on this device. |
| `imd skills remove <id>` | `<id>` | Opt out of a skill; restart the worker for the advertised capability to change. |
| `imd tools` or `imd tools list` | None | List configured local stdio MCP tools and whether they are ready. |
| `imd tools add` | Interactive prompts | Configure an installed stdio MCP server step by step. |
| `imd tools add <id> --command <absolute-path>` | Repeatable `--arg <value>`, `--env <NAME>`, `--probe <value>`, and `--enable <method>` | Configure in one command. `--command` and at least one `--enable` are required. The executable must be an absolute path; `--probe` defaults to `--version`. `--env` records variable names; values are supplied in the worker shell or stored with `tools key`. |
| `imd tools key <NAME>` | `<NAME>` then hidden secret prompt | Store a tool's environment-variable value locally without echoing it. |
| `imd tools forget <NAME>` | `<NAME>` | Remove a stored tool variable. |
| `imd tools remove <id>` | `<id>` | Remove a configured tool. |
| `imd rpc` or `imd rpc list` | None | List configured RPC chain IDs and provider hosts (the URL's secret/path are redacted). |
| `imd rpc add <chain-id>` | `<chain-id>` then hidden URL prompt | Add or replace a provider URL; the CLI checks that it answers for the requested chain. |
| `imd rpc remove <chain-id>` | `<chain-id>` | Remove the local provider for that chain. |

Configured tool values and RPC URLs are local configuration; the README says task access to an RPC is proxied through the worker, and the network learns the chain availability rather than the provider URL. [README: tools](https://github.com/Identity-md/worker/blob/main/README.md#tools), [README: own RPC](https://github.com/Identity-md/worker/blob/main/README.md#your-own-rpc), [CLI help and command implementations](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js)

## Site publishing, launch check, and media task shim

| Command | Options / arguments | Purpose |
|---|---|---|
| `imd site publish <dir> --name <label>` | Directory and required `--name <label>` | Bundle and publish the contributor's own static site. An `index.html` can be at the directory root or under `dist/`, `out/`, or `public/`. The device signs the publish request. |
| `imd site publish --cid <cid> --name <label>` | Required `--cid <cid>` and `--name <label>` | Publish content already pinned to IPFS. |
| `imd site status <site-id>` | `<site-id>` | Check publication status. |
| `imd site names` | None | Print site-label rules. Labels are 3–32 lowercase letters, digits, or hyphens and subject to reserved/claimed-name rules; repeated publication replaces the contributor's site. |
| `imd launch check [dir]` | Optional repository directory, default `.` | Build a launch repository and check its `launch.json` against that build. |
| `imd media <program> [arguments…]` | Pass-through program arguments; no separate option set | Internal media-task shim for running the media tools (for example, ffmpeg/ffprobe) within the task workspace. It is not listed in the operator-facing help. The implementation refuses calls outside a media task and constrains file paths and protocols. |

Site publishing uses the paired device identity to sign; it is for the owner's site, not a command to publish a job's output. `site publish` accepts either a local directory or an already-pinned CID, and `site status` is the follow-up query. [README: own site](https://github.com/Identity-md/worker/blob/main/README.md#your-own-site), [CLI site usage and implementation](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js). `launch check` and `media` are visible in the committed CLI implementation/help or task support code, not explained in the README's main usage sections. [CLI dispatcher, launch, and media implementation](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js)

## Identity, keys, signing, exports, and tokens

- **Pairing / seat token:** `imd pair` runs the wallet authorization flow and records the NFT token ID locally. A token that needs agent registration must be registered by the wallet holder through the pairing page before the control plane admits the worker. One NFT authorizes one active device, according to the README. [README: start and pair](https://github.com/Identity-md/worker/blob/main/README.md#start-and-pair)
- **Device identity:** `imd whoami` prints the device key identifier. The README locates the private device key in `~/.identitymd/config.json` and says to keep it private. `imd unlink` clears the server binding but keeps the local device key. There is no documented command to export or print that private key. [README: updates](https://github.com/Identity-md/worker/blob/main/README.md#updates), [CLI identity commands](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js)
- **Signing:** the implementation signs site-publish requests with the paired device private key. The README also describes the device key as proof for publishing, without a wallet signature or gas fee. No arbitrary message-signing subcommand appears in the CLI dispatcher. [README: own site](https://github.com/Identity-md/worker/blob/main/README.md#your-own-site), [CLI site implementation and dispatcher](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js)
- **Exports:** `site publish` is the CLI's static-site publishing/export path. It bundles the supplied static site or accepts a pre-pinned IPFS CID. The README says accepted task media is pinned and committed with a `MEDIA.md` index on delivery; that is worker delivery behavior, not a user-facing export subcommand. [README: own site](https://github.com/Identity-md/worker/blob/main/README.md#your-own-site), [README media note](https://github.com/Identity-md/worker/blob/main/README.md#your-own-rpc), [CLI site implementation](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js)
- **Tokens:** `status` reports the paired NFT token ID; pairing yields/records that token ID. `tools key` stores a tool credential, and `rpc add` stores an RPC URL, both via hidden prompts. The CLI does not document an access-token creation/export command. [CLI status, pair, tools and RPC implementations](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js), [README: tools](https://github.com/Identity-md/worker/blob/main/README.md#tools)

## Evidence, inferences, and open questions

**Facts from primary sources:** The worker repo identifies itself as the installable CLI distribution, generated from the main development repository. Its committed CLI contains the command dispatcher and built-in usage text; the README documents pairing, runtime setup, service operation, tools, RPC, updates, and site publishing. This reference reports the built-in help and command implementation for the reviewed commit, plus documented README behavior. [Official repository](https://github.com/Identity-md/worker), [committed CLI](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js), [README](https://github.com/Identity-md/worker/blob/main/README.md)

**Inferences:** “Device key identifier” is called public because the CLI prints the `deviceKey` field, while the README distinguishes the private device key stored alongside configuration. This is an interpretation of those separate source descriptions. Likewise, no arbitrary signing or token-export command is listed because no such command appears in the committed dispatcher/help; that is bounded to this CLI build and cannot establish what a separate backend or future build might provide.

**Uncertainty / unanswered:** CLI behavior and default model/provider/network settings can change after this reviewed commit; check the repository's current help/source before relying on details for another release. The README notes that backend source and service credentials are not part of this distribution, so this reference does not claim to enumerate control-plane operations or private backend-only features. The `media` route is present in the implementation but omitted from operator help, and its intended invocation is task-scoped; users should treat it as an internal helper rather than a general command. [README: distribution contents](https://github.com/Identity-md/worker/blob/main/README.md#distribution-contents), [committed CLI](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js)

## Sources

1. [IdentityMD worker repository](https://github.com/Identity-md/worker) — official public distribution, README and release context.
2. [Worker README](https://github.com/Identity-md/worker/blob/main/README.md) — operator installation and workflow documentation.
3. [Committed `dist/cli.js` at `dbdcf99`](https://github.com/Identity-md/worker/blob/dbdcf99c3466264c827dc5afca3bc6906e436373/dist/cli.js) — implementation/help source used to inventory the command tree and options.