An Emacs interface for the Stellar CLI (stellar), in the style of Magit.
Transient menus build the command, the CLI runs it, and every call is
logged, so you learn the CLI while you use Emacs.
It includes a tutorial that goes from a funded testnet account to a Soroban contract with state and a payment signed by two keys. Each step can be done from the menus or typed in a shell; the tutorial asks the CLI whether the step is really done.
- Tutorial checked against the CLI (
M-x stellar-walkthrough). Fifteen steps: tools, network, identities, Friendbot, a Soroban project, build, deploy, a contract call, a counter contract with a constructor and state, a 2-of-2 account and a payment signed by both keys.v(“I did it”) asks the CLI or the ledger whether the step is done, and the tutorial resumes at the first step that is not. - Transaction buffer. Decodes an envelope, shows each operation with its fields and the threshold it needs, and each signature with the identity that made it. Signs, simulates, bumps the sequence number and sends.
- Multisig view. Thresholds, master weight and signers of an account. Each change builds a set-options transaction for you to sign with enough keys and send. A change that leaves a threshold out of reach is refused.
- Contract calls from the spec.
stellar contract info interfacetells the package the type of each argument, and each type gets its own prompt. Integers stay strings, soi128values are exact. A call built for signing is simulated first; the transaction buffer shows its resource fee and each address that still has to authorize it. - Contract development.
stellar contract init, build in a compilation buffer, deploy with an alias and constructor arguments. - Mainnet guard. Every command that signs or submits goes through one
check that identifies the network by its passphrase, including aliases,
environment variables and
.envfiles. Mainnet needs a typed “yes” for each command, and the menus and buffers show its name in upper case, in red. - Log. Each CLI call with its exit code, stdout and stderr in
*stellar-log*, with secret keys and seed phrases redacted. - Thing at point. Accounts, contracts, muxed accounts, signer keys and secret keys (with their checksum), transaction hashes and envelope XDR.
- Emacs 29.1 or newer and
transient0.7 or newer. stellar-cli27 or newer.- For the contract steps: Rust with the
wasm32v1-nonetarget.
The Nix flake provides all of them on macOS.
git clone https://github.com/hpmaxi/stellar-mode.git
cd stellar-mode
nix run .#demoWithout a clone, nix run github:hpmaxi/stellar-mode runs the same
demo from the Nix store.
The demo starts Emacs 30 with a small base config: Zenburn, Vertico,
Marginalia, Orderless, Consult, Embark, Magit, Eglot with rust-analyzer,
and agent-shell with Claude Code.
C-c a starts Claude Code in the tutorial directory with the
Stellar agent skills
linked into .claude/skills.
To keep your own keys out of it, point the CLI at a throwaway config
directory first. STELLAR_CONFIG_HOME changes only where the CLI keeps
its identities and networks; XDG_CONFIG_HOME would also hide your Nix
and Git settings.
export STELLAR_CONFIG_HOME=/tmp/stellar-play
nix run .#demoSee docs/manual-testing.md for a walk through every feature.
With package-vc (Emacs 29.1+):
(package-vc-install "https://github.com/hpmaxi/stellar-mode")With use-package and a local checkout:
(use-package stellar-mode
:load-path "/path/to/stellar-mode"
:bind (("C-c s" . stellar-dispatch)
("C-c W" . stellar-walkthrough)
("C-c S" . stellar-at-point-menu)))The package does not bind any key by itself. M-x stellar (an alias
of stellar-dispatch) opens the main menu, which reaches every other
command.
The heading shows the network and source identity that commands use.
Commands use them without asking, and ask for an identity only when
there is no source. Press C-u before a command’s key to choose
another network or identity for that call.
| Key | Command |
|---|---|
-n | Session network (press again for the CLI default) |
-s | Session source identity (press again for the CLI default) |
c | Contracts: init, build, deploy, invoke, read storage |
i | Call a contract function |
t | Open a transaction envelope |
m | Multisig view of an account |
k | Identities: list, generate (C-u also funds), fund |
n | Networks: session network, health, local container |
l | Log of CLI calls |
x | Stop a running command (only while one runs) |
g | Forget cached data and read the CLI settings again |
W | Tutorial |
e | Stellar Expert: account, contract, transaction |
. | Actions for the thing at point |
The local container menu (n c) starts a Stellar quickstart container
for the local network, or with C-u for testnet, futurenet or pubnet.
-n names the container and -p maps its ports; k stops a container
by name.
k l in the main menu lists the identities of the CLI config.
| Key | Action |
|---|---|
f | Fund the identity at point with Friendbot |
c w | Copy its address |
m RET | Open its multisig view |
g | Read the identities again |
The network is chosen when the buffer opens (call stellar-tx-open with
C-u to pick it), and N changes it. Opening the same envelope on the
same network again shows its buffer. b refuses an envelope that the
network already applied, since the copy would run the same operations
again. Killing the buffer, or quitting Emacs, while it holds signatures
that were not copied, saved or sent asks first.
| Key | Action |
|---|---|
s | Sign with an identity |
x | Simulate a contract call and keep the assembled envelope |
b | Set the next sequence number and remove the signatures |
u | Go back to the envelope before the last sign or change |
P | Send |
e | Open the sent transaction in Stellar Expert |
w | Copy the XDR |
W | Save the XDR to a file, asking before replacing one |
N | Use another network for this transaction |
g | Decode again |
? | Menu of these commands |
| Key | Action |
|---|---|
a | Add a signer with a weight |
RET | Change the weight of the signer at point |
d | Remove the signer at point |
w | Copy the address of the signer at point |
t | Set the low, medium and high thresholds |
M | Set the master key weight |
g | Read the account again |
? | Menu of these commands |
Each change opens a transaction buffer: sign it with keys whose weights
reach the current high threshold, then press P. The buffer shows the
weight signed so far. C-u overrides the lockout check, after a typed
confirmation. P reads the account once more and asks before sending
a change that would lock it, since other changes may have been sent in
the meantime.
| Key | Action |
|---|---|
RET | Menu of the step at point |
x | Do the step with stellar-mode, then check it |
o | Open the stellar-mode menu where the step lives |
v | “I did it”: ask the CLI whether the step is done |
c | Copy the CLI commands of the step |
n p | Next and previous step |
g | Check every step again from the first |
H | Record the hash of a payment sent from a shell |
l | Log of CLI calls |
? | Menu of these commands |
Progress is saved per network and identity in
stellar-walkthrough-state-file. The counter contract that the
tutorial deploys is in tutorial/counter/.
In the identities, transaction and multisig tables, S sorts by the
column at point, and { and } make that column narrower or wider.
g reads the data again and keeps the order and the widths.
nix develop -c make compile # byte-compile, warnings are errors; keeps no .elc
nix develop -c make test # ERT tests against the fake CLI
nix develop -c make check-cli # run the tests' CLI calls through the real CLI
nix develop -c make lint # checkdoc and package-lint
nix develop -c make demo # the demo, from the devshell
nix develop -c gitleaks dir . # look for secret keys and seed phrasesCI scans the whole history with gitleaks. .pre-commit-config.yaml
scans staged changes; install it with prek install or
pre-commit install.
The tests run against test/fixtures/fake-stellar, which accepts the
argument syntax of stellar-cli 27 and answers with output captured from
the real CLI. An argument the real CLI rejects makes it exit with code 2.
The tutorial tests use test/fixtures/fake-stellar-tutorial, which keeps
ledger state between calls.
make check-cli runs the tests, then runs each argument list they gave
the fake through the real stellar on PATH, with an empty configuration,
a network that does not exist and no Docker. It fails when the real CLI
and the fake disagree on whether the arguments are valid.
CI also runs make compile test outside the devshell on Emacs 29.1 and
30.2. When Emacs has a transient older than 0.7, the Makefile installs
the current one from GNU ELPA into .elpa/.
If stellar-mode is useful to you, you can send XLM or any Stellar asset to:
GAFSIUY5C5K7TSJO3ECCXXXE7EFQ7AZCHZGBKTDMLHGSP6QROPGVGRCQ
Check the address before you send: it is a public account key, so it
starts with G and its checksum is valid. With the package loaded, put
point on it and press M-x stellar-at-point-menu to open it in Stellar
Expert.
MIT. See LICENSE.