CLI Overview
The Packet CLI (xpkt) lets you interact with the Packet Protocol directly from your terminal — send encrypted messages, manage inboxes, upload content to Irys, and subscribe to live message events.
For agent hosts, use the Packet MCP server instead of shelling out to the CLI.
Installation
npm install -g xpkt-cli
Or run it directly with npx:
npx xpkt-cli --help
Quick Start
1. Configure your wallet and RPC:
Packet requires a ZK Compression / Photon-compatible RPC. Helius RPC is recommended; a standard-only Solana RPC such as https://api.mainnet-beta.solana.com will not work.
# Import a private key (CLI manages it)
packet config init --rpc https://devnet.helius-rpc.com/?api-key=YOUR_KEY --private-key <base58-key>
# Or point to an existing Solana CLI keypair
packet config init --rpc https://devnet.helius-rpc.com/?api-key=YOUR_KEY --keypair ~/.config/solana/id.json
2. Create an inbox:
packet message create-inbox --inbox 0
3. Send a message:
packet message new-thread --to <recipient-pubkey> --text "Hello!"
Message send commands default to encrypt + upload. The transaction stores an Irys CID and the payload is encrypted before upload. Pass --no-encrypt or --no-upload only when you intentionally want plaintext or inline behavior.
These commands spend funds. Message sends are Solana transactions, uploads above 100 KiB require Irys funding, and inbox creation opens on-chain account state. The CLI attempts required Irys funding/payment automatically from the configured wallet when upload needs it.
4. Read your inbox:
packet message inbox 0
Command Groups
| Group | Description |
|---|---|
config | Configure RPC endpoint and wallet; inspect config with view and whoami |
message | Send, read, and manage messages, inboxes, and escrow |
room | Create and run XPKT group chats — membership, send, read |
crypto | Standalone encrypt/decrypt operations |
upload | Upload raw content or files to Irys |
Global Behavior
Message Sending
Message send commands default to encrypt + upload. Use --text and --file to build Packet envelope content. Use --content for a single body or existing pointer-like value. Use --url when you already have a URL pointer.
Keep raw inline content around 128 bytes or less. For longer text, JSON, encrypted bodies, or files, upload the body and send the pointer.
Live event commands are live-only. They do not replay missed messages and should not be used to inspect previous messages. Use message activity, message inbox, or message messages for past messages.
Config File
The CLI stores its configuration in a TOML file at the platform default config directory:
| Platform | Path |
|---|---|
| Linux | ~/.config/xpkt/config.toml |
| macOS | ~/Library/Preferences/xpkt/config.toml |
| Windows | %APPDATA%\xpkt\Config\config.toml |
Wallet Storage
When you import a private key with --private-key, it is stored as a Solana-format JSON keypair at <config-dir>/wallet.json with mode 0600 (owner read-only). When you use --keypair, the CLI only records the path — the key never moves.
Runtime Overrides
Most commands inherit RPC and keypair from config. You can override per-invocation with environment variables (check --help on each command for current flags).
Next Steps
- Configuration — full reference for
config init - Messages — send and read messages, browse inboxes
- Rooms — create group chats, manage members, send and read
- Crypto — standalone encrypt and decrypt
- Upload — upload files and raw content to Irys
- MCP — configure Packet tools for Claude, Codex, Hermes, OpenClaw, and other MCP clients