Skip to content
Open app

SDK and APICLI

CLI

Open an inbox, buy a pass, send and scan from a terminal with `talaria`.

talaria is the SDK in a terminal. It signs with a Solana keypair file, proves with the same circuit the app uses, and sends through the same relays. Every command is one SDK call: openInbox, buyPass, passes, send and scan.

Install#

The CLI is the @talaria/cli package in backend/cli/, built with the rest of the backend on Node 22:

Shell
cd backend
npm ci
npm run build

The build writes cli/dist/main.js, the package's talaria bin. Run it with Node:

Shell
node cli/dist/main.js pass

The commands below write it as talaria.

Commands#

CommandWhat it does
talaria inbox openOpens this keypair's inbox: signs the key message, then open_inbox
talaria pass buy <light|daily|frequent> <days>Buys a pass of that tier and length
talaria passPrints the pass in use: today's count, days left, expiry
talaria send <wallet | name.sol> <text>Sends a message to a wallet address or a .sol name
talaria scan [--follow]Prints every message to and from this wallet in the Log; with --follow, keeps printing new ones

Every word after the target in send is joined with single spaces into the text, so quote a text that holds several spaces or shell characters.

talaria inbox open#

Shell
talaria inbox open --keypair wallet.json

Prints each stage of the transaction on its own line (building, signing, confirming, indexed), then:

Text
inbox open for <wallet> (<signature>)

The keypair pays the Inbox account's rent and the network fee. Inboxes and keys covers what the inbox holds.

talaria pass buy#

Shell
talaria pass buy light 30

The tier is one of the ids light, daily and frequent, and the days one of the configured lengths (30, 90, 365 as development defaults). Prints the transaction's stages, then:

Text
pass <id> in the pool at leaf <index>: <daily limit> a day until day <expiry day>

The price is taken from the keypair's balance. Passes gives every price and how the days are counted.

talaria pass#

Shell
talaria pass

Prints one line for the pass the next message will use:

Text
<status>: <used> of <daily limit> today, <days left> days left, expires <expiry, UTC>

<status> is active, limit-reached or expired. A wallet with no pass prints no pass.

talaria send#

Shell
talaria send ari.sol "Meet at 12:00 UTC"

Prints each part's stages as they happen:

LineStage
encryptingthe part is encrypted to the reader's inbox key
provingthe proof is being generated for this part and relay
relaying via <relay URL>the part is handed to that relay
landed <signature>the part is in the Log
failed: <code> <message>the part failed; the code is in Errors

A failed relay is followed by the next relay's proving and relaying lines. When every part has landed:

Text
sent in <n> post(s): <signature> <signature> ...

A long text is sent as several parts, one post each; each part counts once against the pass's daily limit.

talaria scan#

Shell
talaria scan
talaria scan --follow

Prints one line for each message found, in Log order:

Text
<sent at, UTC> from <writer>: <text>
<sent at, UTC> to <wallet>: <text>

from is a message written to this wallet; to is one it wrote, found through its own key slot. Without --follow the command ends at the Log's head. With it, it keeps reading the Log until stopped.

Flags#

--keypairpath
The wallet's keypair file, a JSON array of its 64 secret key bytes. Environment: TALARIA_KEYPAIR.

Default ~/.config/solana/id.json

--apiURL
The API. Environment: TALARIA_API_URL.

Default http://127.0.0.1:6710

--relaysURL,URL
The relays to post through, comma-separated. Each part starts at the next relay in the list and tries the others after it. Environment: TALARIA_RELAY_URLS.

Default http://127.0.0.1:6711,http://127.0.0.1:6712

--proverdirectory or URL
Where talaria.wasm, final.zkey and verification_key.json are: a local folder such as backend/circuits/build, or the base URL the site serves them from. Environment: TALARIA_PROVER.

Default http://127.0.0.1:6701/prover

--homedirectory
Where this device's history is kept. Environment: TALARIA_HOME.

Default ~/.talaria

--nameslocal | sns
Where .sol names resolve, on this machine: local, the local build's table (ari.sol, bo.sol, cy.sol, talaria.sol); sns, the SPL Name Service read over --rpc, second-level names. Any other value is taken as local. Environment: TALARIA_NAMES.

Default local

--rpcURL
The Solana RPC that --names sns reads name accounts from. Environment: TALARIA_RPC_URL.

Default http://127.0.0.1:6730

--followflag
With scan: keep following the Log.

A flag wins over its environment variable.

History on disk#

The CLI keeps the same device state the app keeps in IndexedDB, as one file per wallet: <home>/<wallet>.history. The SDK encrypts it with the local history key derived from the wallet's key signature before it is written, so the file holds no readable message, thread or pass. Delete it and scan from a fresh home finds everything again from the Log.

Exit codes#

CodeWhen
0the command finished, or no command was given (the usage is printed)
1the command failed; the reason is written to stderr
2the command was not recognised; the usage is printed