IdentityMD worker daemon CLI reference

Reviewed: 2026-10-16
Scope: the imd CLI in the official IdentityMD worker distribution, specifically the committed CLI at dbdcf99 (dist/cli.js). Its built-in help identifies itself as daemon v0.1.2+63e0a393. The official README 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
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, pair implementation
imd start	--server <url>; --concurrency <1-4>; `--runtime claude	codex; --auto-update`
imd status	None	Show local config state, device key, paired token ID, capacity, runtime detection, and server eligibility when reachable. status implementation
imd doctor	`--runtime claude	codex`
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
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
imd update	None	Update a release installation or update a source checkout using the update mechanism available to that installation. README: updates, update implementation
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

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, CLI dispatcher

Background service

Command	Options / arguments	Purpose
imd service install	`--runtime claude	codex; --concurrency <1-4>; --auto-update; --boot`
imd service restart	`--runtime claude	codex`
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, service usage and parser

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, README: own RPC, CLI help and command implementations

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, CLI site usage and implementation. 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

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
• 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, CLI identity commands
• 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, CLI site implementation and dispatcher
• 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, README media note, CLI site implementation
• 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, README: 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, committed CLI, README

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, committed CLI

Sources

1. IdentityMD worker repository — official public distribution, README and release context.
2. Worker README — operator installation and workflow documentation.
3. Committed dist/cli.js at dbdcf99 — implementation/help source used to inventory the command tree and options.