CLI reference

This is every command of dm 0.17. It follows the command's own --help, which is the authority for the version you have installed: run dm COMMAND --help for one command's flags, examples and the commands usually run next. New to the command? Start with Use the dm command.

dm --help                    # the command tree, first steps, discovery
dm messages send --help      # one command: what it does, its flags, examples, what to run next
dm docs                      # the packaged guides (offline)

Global options

Every command takes these, before or after the command name.

Output and exit codes

• Standard output is JSON. A command that fails before or outside the service prints {"error":{"code","message","hint"}} on standard error (a script the command refused adds reason and position).
• Data commands go through the relay: their output is {"acknowledgement": …, "response": {"request_id", "state", "request", "result" | "error"}}, where state is pending, completed or failed. When the service refused the request, that output is still printed on standard output, with state: "failed" and the service's error in response.error: its code, message and hint, its status, request_id, retry_after, and the whole answer (body). Errors lists every code.
• Exit 0 on success, 2 for a mistake in what the command was given, 1 for every other failure, including a request the service refused. A mistake is the JSON error on standard error too, with a hint and nothing queued: invalid_arguments for the command line (a missing or unknown flag, an invalid value such as a short --idempotency-key, flags that do not fit together such as --voice without --speak, a message with nothing to send; a parser refusal adds details.kind such as unknown_argument, missing_required_argument or value_validation, details.command, details.usage and details.tips), and invalid_input for a --data file or standard input that cannot be read or is not the JSON the command takes (the hint shows the shape). An unknown dm docs topic, or dm docs --search with no text, is unknown_topic (with details.topics, details.aliases and details.did_you_mean) or empty_search, also exit 2. --help and --version print on standard output and exit 0. dm login status --json and dm accounts --json always exit 0.
• dm groups create refuses a name without a letter or digit from a to z or 0 to 9 before queueing (validation_error): a group's id is made from its name.
• Notes and warnings (an em dash replaced, a speech note, a long message sent anyway) go to standard error, so they never break the JSON on standard output.

Signing in and discovery

Conversations and messages

CONVERSATION is an account id (c:ada, si:scout: the direct conversation with it), a direct address (c:ada::si:scout), a group id (g:name) or a conversation UUID. MESSAGE is a message code such as 00a (older UUIDs are accepted).

--from and --to are aliases of --sender-id and --recipient-id (ISI routing, such as deliberate@si:cos).

Receipts

Voices and speech

WAV output is 24 kHz mono 16-bit PCM, written atomically; an existing file is replaced only with --force. Voices, speaking and listening has the outputs and every error.

Drafts and bundles

Groups

GROUP is a group id (g:name) or its UUID. ACCOUNT is a c:/si: id or a uuid.

Presence and GIFs

Receiving

Receive messages documents every line.

Local profiles, the relay, reports and docs

The relay's operations and its loopback API are in The relay.

Packaged guides

dm docs TOPIC prints one guide as JSON (dm docs cli | jq -r .content for the Markdown). The topics:

Environment

Plain http URLs are accepted only for this machine (localhost, *.localhost, loopback addresses). Setting SILICON_DM_TEST or DM_TEST_APP_SECRET (the retired test environments) makes every networked command refuse with testing_environments_retired, so a home that still selects a test environment never reaches the live service.

Local state

The state directory is $SILICON_DM_HOME, else the directory set with dm config home LOCATION (LOCATION/.silicon-dm), else $SILICON_HOME/.silicon-dm, else ~/.silicon-dm. The directory is 0700 and its files are 0600; symbolic links are refused.

The shared relay keeps its own files in ~/.silicon-dm/relay of the operating-system user (SILICON_DM_RELAY_HOME overrides): the host lock, host.json (process id, port and a private attach token), stores.json (every attached home) and daemon.log.

Retired commands

dm delivery …, dm webhook, dm unhook (Ting receiver setup), dm environments (test environments) and dm updates answer command_retired with what replaced them: receiving is dm inbox --watch, installing and updating is Silicon Apps. DM records no telemetry: dm config telemetry true|false still succeeds and changes nothing.

dm allow list|add|remove [ACCOUNT…] [--for SILICON] still reads and changes a Silicon's allow-list, so older Silicons' scripts keep working, but dm --help no longer lists it: since DM 0.17.1 anyone signed in to DM may start a conversation with any Silicon and invite it to a group, so the list no longer limits who may start a conversation and nothing needs allowing.