Using dmbridge from an agent

This guide is for automated agents and scripts operating an installed dmbridge CLI. Repository contributors should also follow the root AGENTS.md.

Check the installationCopy Anchor Link

Start by checking the installed contract and local account names:

dmbridge version --no-input
dmbridge accounts list --no-input
dmbridge x doctor --account personal --no-input

Use doctor --schema <name> to discover request and result contracts instead of guessing fields. doctor without --live is local-only. Use --live only when the user has authorized access to the configured provider account.

For unattended calls, normally include:

--no-input --timeout 30s

Use --quiet when stderr diagnostics are not wanted. Do not combine --quiet with verbosity flags.

If another trusted local process refreshes an X account’s OAuth tokens, import the complete credential with accounts import x --request - and refreshMode: "external". dmbridge will not refresh that credential. Never hand-edit the credential file, and never allow two processes to refresh the same token chain. Discover the request contract with x doctor --schema accounts.import.x.request.

Parsing resultsCopy Anchor Link

stdout contains exactly one JSON protocol envelope. stderr contains only progress, warnings, and diagnostics. Always check both the process exit code and the structured ok field.

The envelope uses protocol version 1. Keep provider IDs, account names, cursors, conversation IDs, message IDs, request IDs, and attachment IDs as opaque strings.

On failure, inspect:

• error.code for the specific machine-readable error;
• the process exit code for the broad failure class;
• error.retrySafety before deciding whether to retry.

Retry safe failures only under the caller's bounded retry policy. Never automatically retry an unsafe or never result. An unsafe mutation failure may mean that the provider accepted the operation before the response was lost.

Input and secretsCopy Anchor Link

Pass ordinary targets as arguments. A reply accepts direct text as its second argument. Use that form only when the text may safely appear in shell history and process listings. Pass structured or sensitive bodies with --request <file> or --request - for stdin. Pass an XChat passcode with --secret <file> or --secret -. Never put access tokens, OAuth callback URLs, authorization codes, client secrets, or passcodes in shell arguments, logs, prompts, or persisted transcripts.

Example direct text reply:

dmbridge x messages reply MESSAGE_ID "hello" --account personal --dry-run \
  --no-input --timeout 30s

Example read:

dmbridge x conversations list \
  --account personal --limit 50 --no-input --timeout 30s

Example body through stdin:

printf '%s' '{"type":"text","text":"hello"}' |
  dmbridge x messages send CONVERSATION_ID --account personal --request - \
    --dry-run --no-input --timeout 30s

Mutations and confirmationCopy Anchor Link

Before a mutation, run the exact command with --dry-run and inspect its provider, account, operation, target, and request. A dry run does not contact a provider or change local state.

Execute the real mutation only after the user has authorized that exact action and target. Use --yes only when the user has explicitly authorized bypassing the command's confirmation. --no-input is not authorization; destructive commands without --yes fail closed in non-interactive mode.

Never run provider mutations, replace credentials, replace a passcode, remove an account, acknowledge delivery side effects, overwrite a download, or use a live account merely to explore behavior. Prefer help, local doctor, schemas, dry runs, and offline fixtures.

DiscoveryCopy Anchor Link

Use the CLI itself as the current command inventory:

dmbridge help --no-input
dmbridge x messages --help --no-input
dmbridge x doctor --schema message.send --no-input
dmbridge x doctor --schema accounts.add.request --no-input

Do not scrape README examples as a command registry. Help and doctor output are generated from the runtime definitions and describe the installed version.