XMTP CLI

The XMTP CLI provides terminal commands for identities, conversations, messages, consent, and installations. It connects directly to an XMTP backend through a required URL.

Install

Use this repository’s CLI with its matching Node SDK. The npm registry has CLI 0.2.0; this checkout’s CLI 0.3.0 is not published. Install the workspace dependencies and build the CLI from the repository root with Nix installed:

dev/nix-shell 'just install-js'
dev/nix-shell 'just cli build'

Run all commands below from that same repository root.

Initialize

Choose the backend explicitly when generating the local configuration:

dev/nix-shell 'node apps/cli/bin/run.js init --backend-url http://127.0.0.1:5050'

This writes wallet and database-encryption keys, the backend URL, and the database label to ~/.xmtp/.env. Later commands use flags first, then process environment variables. They load an explicit --env-file when supplied. Otherwise, they load ./.env, or ~/.xmtp/.env if the local file cannot be loaded. Values already in the process environment take precedence over the file.

Use the CLI

dev/nix-shell 'node apps/cli/bin/run.js client info'
dev/nix-shell 'node apps/cli/bin/run.js can-message 0x...'
dev/nix-shell 'node apps/cli/bin/run.js conversations create-dm 0x...'
dev/nix-shell 'node apps/cli/bin/run.js conversation send-text "<conversation-id>" "Hello"'
dev/nix-shell 'node apps/cli/bin/run.js conversation messages "<conversation-id>"'

Replace 0x... with the recipient’s registered Ethereum address, and <conversation-id> with the returned conversation ID. Use --json for structured output. Add --help to a command for its command and flag details.

Backend-specific databases

By default, the CLI stores data for the local label at ~/.xmtp/<backend-label>/xmtp-db. A new database with another environment label uses ~/.xmtp/<backend-label>/environments/<environment-label>/xmtp-db. If the earlier path already has a database, the CLI keeps using it. If both paths have databases, set --db-path or XMTP_DB_PATH to select one. The backend label comes from the backend origin. An explicit path stays unchanged.

--env and XMTP_ENV are database labels only. They do not choose a backend.