amethyst/cli/README.md

Amy — Amethyst CLI

amy is the non-interactive command-line face of Amethyst. It speaks the same Nostr protocol as the Android and Desktop apps, shares the same quartz and commons code, and aims to eventually expose every feature the GUI offers as a command you can script.

Amy exists for three audiences at once:

1. Humans using Amethyst from a terminal or remote shell.
2. Agents / LLMs driving a Nostr account through a deterministic, JSON-typed interface — no interactive prompts, no screen scraping.
3. Interop test harnesses that put Amethyst side-by-side with the other ~100 Nostr clients publishing and consuming the same events. Any flow that is tested in the Amethyst app should be reproducible through amy — that's the bar.

Today Amy covers identity, relay config, account bootstrap, and Marmot / MLS group chat (MIP-00 / NIP-445). Everything else from the Android app is on the roadmap — see ROADMAP.md.

To extend Amy, see DEVELOPMENT.md.

---

Output contract

What every caller — user, script, agent, CI — can rely on:

• stdout is JSON. One line. One object. Stable snake_case keys. Pipe it into jq, parse it from Python, hand it to an agent.
• stderr is for humans. Progress, warnings, per-relay ACK traces. Safe to discard.
• Exit codes are the real signal.
  • 0 — success
  • 1 — runtime error (JSON {"error":"…","detail":"…"} on stderr)
  • 2 — bad arguments
  • 124 — await timed out
• No interactive prompts, ever. Passwords, names, keys — all flags.
• Data-dir is the whole world. All state (identity, relays, MLS epochs, message archives, run cursors) lives under --data-dir PATH. Delete to reset; copy to move; AMETHYST_CLI_DATA env var overrides the default ./amy.

The rationale behind each of these lives in DEVELOPMENT.md. Breaking any of them is a breaking change to Amy's public API.

---

Install

Until Amy ships as a signed native binary (see cli/plans/2026-04-21-cli-distribution.md), run it from source:

# One-shot run — positional args go after `--args`, quoted as one string
./gradlew :cli:run --quiet --args="whoami"

# Or build a runnable distribution and use the generated launch script
./gradlew :cli:installDist
./cli/build/install/amy/bin/amy whoami

The installDist tree under cli/build/install/amy/ is self-contained (JVM launcher + jars) and is what downstream packaging will wrap.

Requirements: JDK 21.

---

Quick start

# 1. Create a data-dir with a full Amethyst-style account.
#    Generates a keypair, seeds default NIP-65 / inbox / key-package
#    relays, and publishes the nine bootstrap events.
amy --data-dir ./alice create --name "Alice"

# 2. Publish a fresh MLS KeyPackage so others can invite you.
amy --data-dir ./alice marmot key-package publish

# 3. Create a group, invite someone, send a message.
amy --data-dir ./alice marmot group create --name "Test Group"
amy --data-dir ./alice marmot group add <GID> npub1...bob
amy --data-dir ./alice marmot message send <GID> "hello"

# 4. On the receiving side — poll until Bob sees the invite.
amy --data-dir ./bob marmot await group --name "Test Group" --timeout 60
amy --data-dir ./bob marmot message list <GID>

Compose with jq to chain commands:

GID=$(amy --data-dir ./alice marmot group create --name "Test" | jq -r .group_id)

For an interop-test script template, see DEVELOPMENT.md § Testing. The runnable harnesses live under cli/tests/ — cli/tests/marmot/ for MLS group messaging vs whitenoise-rs, cli/tests/dm/ for NIP-17 DMs between two amy clients.

---

Command reference

Run amy --help for the canonical list. As of today:

Verb	Summary
init [--nsec NSEC]	Create or import a bare identity. Does not publish anything.
create [--name NAME]	Provision a full account + publish the nine Amethyst bootstrap events.
login KEY [--password X] [--private]	Import nsec / ncryptsec / BIP-39 mnemonic / npub / nprofile / hex / NIP-05. Read-only when no secret material is supplied.
whoami	Print the identity stored in --data-dir.
relay add URL [--type T]	T = nip65 | inbox | key_package | all.
relay list	Dump configured relays by bucket.
relay publish-lists	Publish kind:10002 (NIP-65) + kind:10050 (DM inbox) + kind:10051 (KeyPackage relay list).
marmot key-package publish	Publish a fresh MLS KeyPackage (kind:30443) to the configured key_package bucket (fallback: NIP-65 outbox).
marmot key-package check NPUB	Look up NPUB's kind:10051 / kind:10002 on bootstrap relays, then fetch their KeyPackage from those relays.
marmot group create [--name NAME]	New empty group with you as sole admin.
marmot group list	All groups you're a member of.
marmot group show GID	Full group state (members, admins, epoch, metadata).
marmot group members GID	Members only.
marmot group admins GID	Admins only.
marmot group add GID NPUB [NPUB…]	Fetch KeyPackages for the npubs and commit an add.
marmot group rename GID NAME	Commit a metadata change.
marmot group promote GID NPUB	Make an existing member an admin.
marmot group demote GID NPUB	Revoke admin.
marmot group remove GID NPUB	Remove a member.
marmot group leave GID	Self-remove.
marmot message send GID TEXT	Publish a kind:9 inner event into the group.
marmot message list GID [--limit N]	Decrypted inner events, oldest first.
marmot await key-package NPUB	Block until a KeyPackage is seen on NPUB's advertised relays (kind:10051 / kind:10002).
marmot await group --name NAME	Block until we're added to a group with that name.
marmot await member GID NPUB	Block until NPUB is in GID's member set.
marmot await admin GID NPUB	Block until NPUB is an admin of GID.
marmot await message GID --match TEXT	Block until a message containing TEXT lands.
marmot await rename GID --name NAME	Block until GID's name matches.
marmot await epoch GID --min N	Block until GID's MLS epoch is ≥ N.
dm send RECIPIENT TEXT [--allow-fallback]	Send a NIP-17 gift-wrapped text DM (kind:14 inside kind:1059). Default delivers only to the recipient's kind:10050 (per NIP-17); pass --allow-fallback to fall back to kind:10002 read marker → bootstrap pool.
dm send-file RECIPIENT --file PATH --server URL [--mime-type M] [--allow-fallback]	Encrypt the local file with a fresh AES-GCM cipher, upload the ciphertext to the Blossom server, then publish a kind:15 NIP-17 file message referencing the returned URL. The auto-detected hash, size, dimensions, and blurhash from the upload are folded into the event. The response also surfaces the encryption key + nonce so the same blob can be re-shared without re-uploading.
dm send-file RECIPIENT URL --key HEX --nonce HEX [--mime-type M] [--hash H] [--original-hash H] [--size N] [--dim WxH] [--blurhash S] [--allow-fallback]	Reference-mode variant: the file is already uploaded; --key/--nonce carry the AES-GCM material that recipients use to decrypt the bytes at URL. Useful when the upload happened elsewhere or to re-publish a previously-uploaded blob.
dm list [--peer NPUB] [--since TS] [--limit N] [--timeout SECS]	Drain and decrypt gift wraps on our inbox relays. Returns kind:14 (text) and kind:15 (file) messages with a type discriminator. With neither --peer nor --since the gift-wrap cursor in state.json is advanced to the newest message seen.
dm await --peer NPUB --match TEXT [--timeout SECS]	Block until a DM from NPUB containing TEXT arrives (matches text content for kind:14, URL for kind:15). Timeout exits 124.

All await verbs accept --timeout SECS (default 30). Timeout exits 124 so scripts can distinguish "condition never happened" from "the command itself crashed".

Global flags

• --data-dir PATH — defaults to ./amy or $AMETHYST_CLI_DATA. Always an absolute path after resolution.
• --help / -h — usage summary.

---

Relay routing

Amy follows the Marmot protocol's per-event routing rules so two users with completely disjoint relay configurations can still marmot each other. No event ever ships blindly to "our configured relays" — Amy looks up the right relay set per event per recipient.

Event	Publish to	Fetch from
kind:30443 (our own KeyPackage)	key_package bucket → NIP-65 outbox → any configured	—
kind:30443 (someone else's KeyPackage)	—	Their kind:10051 → their kind:10002 write → our bootstrap pool
kind:10051 / 10050 / 10002 (our own lists)	All configured relays (broadcast)	—
kind:10051 / 10050 / 10002 (someone else's)	—	Our bootstrap pool = configured relays ∪ Amethyst defaults
kind:1059 Welcome gift wrap (kind:444 inside)	Recipient's kind:10050 → their kind:10002 read → DefaultDMRelayList → our outbox	—
kind:1059 gift wraps addressed to us	—	Our kind:10050
kind:445 Group Event (Commit / Proposal / chat)	Group's MIP-01 relays field	Same

Bootstrap pool: when Amy needs to discover a user it's never talked to, it queries configured relays ∪ Amethyst's default NIP-65 set ∪ Amethyst's default DM-inbox set. These defaults come from commons.defaults.AmethystDefaults and match what the Android/Desktop UI publishes to on first run, so any fresh Amethyst account is reachable via the bootstrap pool even before Amy has seen any of their events.

---

Data-dir layout

<data-dir>/
├── identity.json             # nsec/npub/hex — the account
├── relays.json               # nip65 / inbox / key_package buckets
├── state.json                # sync cursors (giftWrapSince, groupSince)
└── marmot/
    ├── keypackages.bundle    # MLS KeyPackage bundles (NostrSignerInternal)
    └── groups/
        ├── <gid>.mls         # MLS group state per group
        └── <gid>.log         # decrypted inner events (one JSON per line)

All files are plain JSON or framed binary — human-inspectable, easy to diff across two data-dirs in a test run.

---

Troubleshooting

• no identity — run init, create, or login first, or pass a different --data-dir.
• not_member — the group GID is unknown to this data-dir. Run marmot group list to confirm, or marmot await group --name … to wait for an invite to arrive.
• Hang on a network verb — Amy connects to the relays in relays.json; verify with amy relay list. Every network-bound operation has a timeout — use --timeout for await, or wrap the whole command in timeout(1) if you're scripting.
• Nothing seems to publish — inspect stderr; each publish prints per-relay OK / REJECT via the [cli] … traces.