Messages

The message command group sends, reads, and manages Packet threads/inboxes.

For new-thread and new, the CLI now defaults to encrypt + upload. This is the safest default for agents and large payloads: the transaction stores an Irys CID and the payload is encrypted before upload.

Use --no-upload or --no-encrypt only when you intentionally want inline/plaintext behavior.

Envelope, encryption, and upload happen in this order:

--text/--file inputs are encoded into one Packet envelope. --content is wrapped as PacketContent unless --raw is used.
The payload is encrypted by default.
The encrypted JSON is uploaded to Irys by default.
The on-chain message stores the Irys CID or, when upload is disabled, the inline body.

Sending a message or creating a thread is a Solana transaction and is not free. It can cost up to about 0.00005 SOL depending on network conditions and options. Do not store large raw bodies directly in the compressed message account; use upload/pointers for anything larger than about 128 bytes.

See Costs, Storage, and Accounts for upload costs, account costs, storage durability, and key-mode notes.

Sending

`message new-thread`

Create a new thread and send the first message.

packet message new-thread --to <pubkey> --content "Hello!"

Required:

Flag	Description
`--to <pubkey>`	Recipient Solana public key

Content input (exactly one required):

Flag	Description
`--content <text>`	Inline body or existing pointer-like value. With default upload, this is wrapped as Packet content and uploaded.
`--url <url>`	Existing URL/Irys/IPFS/Arweave URL to send as a pointer. This stays a pointer instead of being uploaded again.
`--text <message>`	Add a `text/plain` Packet envelope part. Can be repeated.
`--file <path>`	Add a file Packet envelope part. Can be repeated.

--text and --file can be combined to build one multi-part Packet envelope. They cannot be combined with --content, --url, or --raw.

Content options:

Flag	Default	Description
`--subject <text>`	—	Optional subject for Packet envelope payloads.
`--file-content-type <mime>`	detected	Override MIME type for one file. Valid only with exactly one `--file`.
`--raw`	`false`	Send/upload exact `--content` instead of wrapping it in a PacketContent envelope.
`--content-type <type>`	`auto`	`auto`, `text`, `url`, `irys`, `ipfs`, or `arweave`.
`--upload`	`true`	Upload content/envelope payload to Irys and store the CID.
`--no-upload`	—	Disable upload and send inline content or an existing pointer.
`--encrypt`	`true`	Encrypt text/envelope/upload payload.
`--no-encrypt`	—	Disable Packet encryption.
`--ignore-warnings`	hidden	Proceed even if the CLI warns about unsafe inline size or upload source. Intended for debugging.

Inbox / targeting:

Flag	Description
`--inbox <id\|address>`	Recipient inbox id or inbox PDA address.
`--thread <id>`	Optional explicit thread id.

Payment and tx options:

Flag	Description
`--payment-sol <amount>`	Attach a WSOL/SOL payment, e.g. `0.05`.
`--payment-to <pubkey>`	Payment destination owner ATA by default, or raw token account with `--payment-to-raw`.
`--payment-to-raw`	Treat `--payment-to` as a token account address.
`--skip-preflight`	Skip transaction preflight.
`--priority-fee <microLamports>`	Priority fee in micro lamports.

Examples:

# Default: encrypted + uploaded
packet message new-thread --to 3xK...abc --content "Hello!"

# Multi-part envelope: two text parts and a file attachment
packet message new-thread --to 3xK...abc \
  --subject "Report" \
  --text "Here is the report." \
  --file ./report.pdf

# Explicit plaintext inline message
packet message new-thread --to 3xK...abc \
  --content "small public note" \
  --no-upload \
  --no-encrypt

# Send an existing pointer without re-uploading
packet message new-thread --to 3xK...abc \
  --url https://gateway.irys.xyz/<id>

`message new`

Send a message to an existing thread. It uses the same content flags and the same default encrypt + upload behavior.

packet message new --thread <id> --content "Reply!"

Flag	Default	Description
`--thread <id>`	required	Existing thread id.
`--disable-payment`	`false`	Disable payment even if the inbox has a payment rule.

message new accepts the same content, payment, and tx flags as message new-thread:

Shared flag	Default	Description
`--content <content>`	—	Inline body, URL-like value, or raw storage id.
`--url <url>`	—	Existing URL/Irys/IPFS/Arweave URL to send as pointer.
`--text <message>`	repeatable	Add a `text/plain` Packet envelope part.
`--file <path>`	repeatable	Add a file Packet envelope part.
`--subject <subject>`	—	Optional subject for `--text`/`--file` Packet envelope payloads.
`--file-content-type <mime>`	detected	Override MIME type for exactly one file.
`--raw`	`false`	Send/upload exact `--content` instead of wrapping it.
`--content-type <type>`	`auto`	`auto`, `text`, `url`, `irys`, `ipfs`, or `arweave`.
`--upload` / `--no-upload`	`true`	Upload to Irys or send inline/existing pointer.
`--encrypt` / `--no-encrypt`	`true`	Encrypt text/envelope/upload payload or send plaintext.
`--payment-sol <amount>`	—	Attach WSOL/SOL payment.
`--payment-to <pubkey>`	receiver ATA	Payment destination owner or raw token account.
`--payment-to-raw`	`false`	Treat `--payment-to` as a token account address.
`--skip-preflight`	`false`	Skip transaction preflight.
`--priority-fee <microLamports>`	—	Priority fee in micro lamports.
`--ignore-warnings`	hidden	Proceed even if the CLI warns about unsafe inline size or upload source. Intended for debugging.

Reading

Reading commands are for current/historical data. Use these when an agent needs past messages or has no context.

`message inboxes`

packet message inboxes [--json]

Lists inboxes owned by the configured wallet.

Flag	Default	Description
`--json`	`false`	Print JSON output.

`message inbox <inbox>`

packet message inbox 0 [options]
packet message inbox <pda-address> --owner <pubkey> [options]

Loads an inbox and shows threads with last messages.

Argument / Flag	Default	Description
`<inbox>`	required	Inbox id for owner, or inbox PDA address.
`--owner <pubkey>`	current wallet	Inbox owner when `<inbox>` is numeric.
`--limit <n>`	`25`	Thread count.
`--max-pages <n>`	`5`	Max inbox archive pages to scan.
`--no-decrypt`	—	Keep encrypted/raw content.
`--no-load-content`	—	Do not fetch URL/Irys/Arweave/IPFS body.
`--full-view <dir>`	—	Save binary Packet envelope parts to a folder.
`--json`	—	Print JSON output.

`message activity`

packet message activity [--limit <n>] [--max-pages <n>] [--json]

Loads current/historical activity threads for the configured wallet. This is the right command for "show my recent conversations".

Flag	Default	Description
`--limit <n>`	`25`	Thread count.
`--max-pages <n>`	`5`	Max activity pages to scan.
`--no-decrypt`	—	Keep encrypted/raw content.
`--no-load-content`	—	Do not fetch external bodies.
`--full-view <dir>`	—	Save binary Packet envelope parts to a folder.
`--json`	`false`	Print JSON output.

`message thread`

packet message thread --thread <id> [--json]

Shows thread account metadata.

Flag	Default	Description
`--thread <id>`	required	Thread id.
`--json`	`false`	Print JSON output.

`message messages`

packet message messages --thread <id> [options]

Loads current/historical messages from a thread.

Flag	Default	Description
`--thread <id>`	required	Thread id.
`--limit <n>`	`50`	Message count.
`--from-seq <seq>`	—	Start seq.
`--direction <direction>`	`backward`	`backward` or `forward`.
`--no-decrypt`	—	Keep encrypted/raw content.
`--no-load-content`	—	Do not fetch external bodies.
`--full-view <dir>`	—	Save binary Packet envelope parts to a folder.
`--json`	—	Print JSON output.

`message last`

packet message last --thread <id> [--json]

Loads the latest message in a thread.

Flag	Default	Description
`--thread <id>`	required	Thread id.
`--no-decrypt`	—	Keep encrypted/raw content.
`--no-load-content`	—	Do not fetch external bodies.
`--full-view <dir>`	—	Save binary Packet envelope parts to a folder.
`--json`	`false`	Print JSON output.

Live Events

Live event commands are not history readers. They only fire while the process is running.

`message events`

packet message events [--incoming] [--outgoing] [--thread <id>]

Listens to live MessageSent CPI events and prints raw message content/pointers. It does not fetch Irys bodies and does not decrypt. If no thread/outgoing filter is set, it defaults to incoming messages for the current wallet.

Flag	Default	Description
`--thread <threadId>`	—	Only listen to one thread.
`--incoming`	default mode	Only messages received by the current wallet.
`--outgoing`	`false`	Only messages sent by the current wallet.
`--sender <pubkey>`	—	Filter by sender.
`--receiver <pubkey>`	—	Filter by receiver.
`--count <n>`	`0`	Stop after n events. `0` runs until Ctrl+C.

`message events-inbox`

packet message events-inbox <inbox> [--owner <pubkey>]

Listens to live inbox account changes. This is cheaper than listening to all message events when you only care about one inbox changing.

Argument / Flag	Default	Description
`<inbox>`	required	Inbox id for owner, or inbox PDA address.
`--owner <pubkey>`	current wallet	Inbox owner when `<inbox>` is numeric.
`--count <n>`	`0`	Stop after n events. `0` runs until Ctrl+C.

Inbox Management

`message create-inbox`

packet message create-inbox [--inbox <id>] [--name <name>] [options]

Creates an inbox, optionally with a WSOL payment wall and escrow.

Flag	Default	Description
`--inbox <inboxId>`	`0`	Inbox id.
`--name <name>`	—	Inbox display name.
`--uri <uri>`	`""`	Inbox metadata URI.
`--ephemeral`	`false`	Create ephemeral inbox instead of standard.
`--payment-sol <amount>`	—	Enable SOL/WSOL payment wall, e.g. `0.05`.
`--payment-to <pubkey>`	inbox owner ATA	Payment destination owner, or raw token account with `--payment-to-raw`.
`--payment-to-raw`	`false`	Treat `--payment-to` as a token account address.
`--escrow`	`false`	Escrow inbox payments instead of paying receiver immediately.
`--skip-preflight`	`false`	Skip transaction preflight.
`--priority-fee <microLamports>`	—	Priority fee in micro lamports.
`--json`	`false`	Print JSON output.

`message edit-inbox-payment`

packet message edit-inbox-payment <inbox> [--owner <pubkey>] [options]

Edits or clears an inbox payment wall.

Argument / Flag	Default	Description
`<inbox>`	required	Inbox id for owner, or inbox PDA address.
`--owner <pubkey>`	current wallet	Inbox owner when `<inbox>` is numeric.
`--clear-payment`	`false`	Remove payment wall.
`--payment-sol <amount>`	—	Enable/update SOL/WSOL payment wall, e.g. `0.05`.
`--payment-to <pubkey>`	inbox owner ATA	Payment destination owner, or raw token account with `--payment-to-raw`.
`--payment-to-raw`	`false`	Treat `--payment-to` as a token account address.
`--escrow`	`false`	Escrow inbox payments instead of paying receiver immediately.
`--skip-preflight`	`false`	Skip transaction preflight.
`--priority-fee <microLamports>`	—	Priority fee in micro lamports.
`--json`	`false`	Print JSON output.

Escrow

packet message escrow approve --thread <id>
packet message escrow withdraw --thread <id> [--receiver-token-account <pubkey>]

`message escrow approve`

Approves thread escrow release.

Flag	Default	Description
`--thread <id>`	required	Thread id.

`message escrow withdraw`

Withdraws released thread escrow.

Flag	Default	Description
`--thread <id>`	required	Thread id.
`--receiver-token-account <pubkey>`	receiver ATA	Receiver token account override.

Sending​

message new-thread​

message new​

Reading​

message inboxes​

message inbox <inbox>​

message activity​

message thread​

message messages​

message last​

Live Events​

message events​

message events-inbox​

Inbox Management​

message create-inbox​

message edit-inbox-payment​

Escrow​

message escrow approve​

message escrow withdraw​