Skip to content

docs(readme): clarify key setup and remove obsolete env var advice #183

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
grunch merged 2 commits into from
Aug 13, 2026
Merged

docs(readme): clarify key setup and remove obsolete env var advice #183

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
32c0105
docs(readme): clarify key setup and remove obsolete env var advice
grunch Aug 13, 2026
9f4e92b
docs(readme): correct invalid-key FAQ and split RELAYS guidance
grunch Aug 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 45 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,20 @@ mostro-cli --help

This is the part most users skip, and then get confused about. Read it once and the rest of the CLI makes sense.

### You do not bring your own `nsec`

**There is nothing to set up.** `mostro-cli` generates and manages your Nostr keys for you on first run. You never paste an `nsec` for normal trading, and there is no key-generation step to perform beforehand (no `rana`, no `nostr-tool`, no wallet export).

In particular, these variables are **not** read by the CLI and setting them does nothing:

| Variable people try | Reality |
|---|---|
| `NSEC_PRIVKEY` | Obsolete. Removed when the CLI moved to mnemonic-derived keys (NIP-06). |

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve the legacy admin key during migration

For administrators upgrading from older releases, NSEC_PRIVKEY was renamed to ADMIN_NSEC rather than removed by the mnemonic migration; the current init_context still parses that same separately supplied admin secret under its new name. Calling it merely obsolete can lead administrators to discard the credential instead of renaming the environment variable, leaving all admin commands unusable.

Useful? React with 👍 / 👎.

| `MOSTROPUBKEY` | Wrong name — the variable is `MOSTRO_PUBKEY`, with an underscore. |
| `PRIVKEY`, `NSEC` | Never existed. |

The only key you ever supply by hand is `ADMIN_NSEC`, and only if you are a solver/admin — see [Admin / Solver usage](#admin--solver-usage).

### The mnemonic (your master backup)

On first run, the CLI generates a **BIP39 12-word mnemonic** and stores it in a local SQLite database (`~/.mcli/mcli.db`, table `users`). This mnemonic is the seed for everything: lose it and you cannot recover orders or trade keys; share it and someone else can impersonate you.
Expand All @@ -102,7 +116,7 @@ The mnemonic-based user and the admin key are completely independent. You can ru

## Configuration

`mostro-cli` reads its configuration from environment variables (or equivalent CLI flags). The Mostro pubkey and at least one relay are mandatory.
`mostro-cli` reads its configuration from environment variables (or equivalent CLI flags). The Mostro pubkey and at least one relay are mandatory. **Your own keys are not part of the configuration** — see [You do not bring your own `nsec`](#you-do-not-bring-your-own-nsec).

### Required

Expand All @@ -117,6 +131,7 @@ The mnemonic-based user and the admin key are completely independent. You can ru
|---|---|---|
| `POW` | `-p, --pow` | Proof-of-work difficulty (bits) required by the Mostro instance for incoming events. Set this if the daemon enforces PoW. |
| `SECRET` | `--secret` | Use secret/anonymous mode for the inner event tuple (advanced, hides trade index from gift-wrap inner). |
| `TRANSPORT` | `-t, --transport` | Wire transport: `gift-wrap` (protocol v1) or `nip44` (protocol v2). Leave unset to auto-detect from the instance's info event. |
| `ADMIN_NSEC` | — | Admin/solver private key in `nsec1...` or hex format. Only read when an `adm*` command is invoked. |
| `RUST_LOG` | `-v, --verbose` | Verbose logging. The `-v` flag sets `RUST_LOG=info` for you. |

Expand All @@ -139,6 +154,26 @@ mostro-cli listorders

> Pubkeys above are illustrative — replace them with the actual Mostro instance and relays you want to trade on.

### About `.env` files

`mostro-cli` does **not** load a `.env` file automatically — there is no dotenv support in the binary, so dropping a `.env` next to the executable has no effect. Older guides (and some issue comments) suggest it; that advice is outdated.

If you prefer keeping settings in a `.env`-style file, export them yourself before running the CLI:

```bash
# ~/.config/mostro/.env (chmod 600)
MOSTRO_PUBKEY=npub1ykvsmrmw2hk7jgxgy64zr8tfkx4nnjhq9eyfxdlg3caha3ph0skq6jr3z0
RELAYS=wss://relay.mostro.network,wss://relay.damus.io
POW=0
```

```bash
set -a; source ~/.config/mostro/.env; set +a
mostro-cli listorders
```

`set -a` marks every variable assigned by the file for export, so the CLI sees them; `set +a` turns that back off.

---

## Quick start
Expand Down Expand Up @@ -485,6 +520,7 @@ Every command supports `-h, --help`. The list below is a one-line summary; run `
- `-r, --relays <list>` — overrides `RELAYS`.
- `-p, --pow <bits>` — overrides `POW`.
- `--secret` — secret mode for inner event tuple.
- `-t, --transport <gift-wrap|nip44>` — overrides `TRANSPORT` (auto-detected when unset).

---

Expand All @@ -503,6 +539,7 @@ Environment variables read by the CLI:
| `RELAYS` | Required — Nostr relays. |
| `POW` | Optional — proof-of-work bits. |
| `SECRET` | Optional — `true` enables secret-mode inner tuple. |
| `TRANSPORT` | Optional — `gift-wrap` or `nip44`; auto-detected when unset. |
| `ADMIN_NSEC` | Optional — only used by admin commands. |
| `RUST_LOG` | Optional — verbose logging level. |

Expand All @@ -516,7 +553,13 @@ The database stores **secret material** (your mnemonic). Treat `~/.mcli/mcli.db`

## Troubleshooting / FAQ

**`MOSTRO_PUBKEY not set`** — Export it or pass `-m <npub>`. Same for `RELAYS`.
**`Failed to get context keys: Invalid secret key`** — You are setting `NSEC_PRIVKEY` (or another obsolete key variable). The CLI no longer accepts a user-supplied `nsec`: it derives its keys from a mnemonic it generates itself. `unset NSEC_PRIVKEY` and just set `MOSTRO_PUBKEY` and `RELAYS`. See [You do not bring your own `nsec`](#you-do-not-bring-your-own-nsec).

@chatgpt-codex-connector chatgpt-codex-connector Bot Aug 13, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Require an upgrade before unsetting the legacy key

For users seeing this exact error, the advice cannot resolve it: Failed to get context keys was emitted by older releases where NSEC_PRIVKEY was mandatory for every invocation, so unsetting it only changes the failure to NSEC_PRIVKEY not set. Current releases no longer emit this message at all; the troubleshooting step needs to tell affected users to upgrade first, and to rename the variable to ADMIN_NSEC if they use admin commands.

Useful? React with 👍 / 👎.

Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated

**"How do I generate my keys?"** — You don't. There is no key-generation step and no need for tools like `rana`. The first command you run creates `~/.mcli/mcli.db` with a fresh BIP39 mnemonic; every identity and trade key is derived from it (NIP-06). Back the mnemonic up — see [Backup, recovery and multi-device](#backup-recovery-and-multi-device).

**`MOSTRO_PUBKEY not set`** — Export it or pass `-m <npub>`. Note the underscore: `MOSTROPUBKEY` (no underscore) is not read. Same for `RELAYS`.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated

**My `.env` file is ignored** — It is not loaded automatically; the CLI has no dotenv support. Use `set -a; source .env; set +a` first — see [About `.env` files](#about-env-files).

**`ADMIN_NSEC not set (required for admin commands)`** — Only admin subcommands need it. Export it in the same shell, or prefix the command: `ADMIN_NSEC=nsec1... mostro-cli admsettle ...`.

Expand Down
Loading