`asentum quickstart` — one command from zero to funded account

Quick one tonight. My testers are mostly on Windows. They've never touched a terminal in their lives. I needed the CLI to stop scaring them.

the old flow

If a Windows noob wanted to try AsentumChain before today, here's what they were up against:

1. Install Node.js (which node? "command not found." now what?)
2. Clone the repo (git is also not installed by default on Windows, cool)
3. Run pnpm install (hope it works, get scared by scrolling warnings)
4. Build (pnpm -r build)
5. Install the CLI (npm link packages/cli — "wait, what's npm link?")
6. Now they have asentum in their path. Great. What do they do with it?
7. asentum → shows a big wall of text help output
8. asentum chain → "error: fetch failed" — a raw Node error because nothing's running on 127.0.0.1:8545 and the CLI has no default RPC
9. Set the env var ($env:ASENTUM_RPC_URL = "https://..." — PowerShell, good luck remembering the syntax)
10. asentum account new alice → works
11. asentum faucet --to alice --amount 100 → works, maybe, if they remember the flags
12. asentum balance alice → shows 0 because they didn't wait for a block
13. Wait, then asentum balance alice → shows balance
14. They give up somewhere around step 7

The CLI worked. It was dev-focused. It wasn't welcoming.

the new flow

One command. No env vars. No flags. No questions.

$ asentum quickstart

Here's what happens:

[1/4] Checking connection…
      ✓ connected to http://127.0.0.1:8545 (height 2)
[2/4] Setting up your account…
      ✓ created new account 'default'
      address: 0x3c2EFa568F952ce8a1A53C87c25D32aCf53ec48A
[3/4] Requesting 100 ASE from the faucet…
      ✓ faucet drip queued — tx 0x938edbdc62e023dd…
[4/4] Waiting for the next block, then showing balance…
      balance: 100 ASE (100000000000000000000 wei)

✓ you are all set  your account is default

  Try next:
    asentum balance             (check your balance any time)
    asentum account new bob     (create a second account)
    asentum send 10 bob         (send 10 ASE to bob)
    asentum chain               (look at the chain state)

Four steps, clear progress on each, friendly green checkmarks, clear error paths for everything that can go wrong, and a "here's what to do next" at the bottom. The noob literally never has to think about faucets or nonces or hex addresses.

the bare asentum command

Running asentum with no arguments used to print a wall of help text. Now it's a smart welcome banner that checks the user's state:

If you have no accounts yet:

  ╔═══════════════════════════════════════════════╗
  ║  AsentumChain — post-quantum L1 blockchain    ║
  ╚═══════════════════════════════════════════════╝

  RPC: http://127.0.0.1:8545

  You have no accounts yet. Get started with one command:

    asentum quickstart

  (creates an account, funds it from the testnet faucet, shows your balance)

If you already have an account:

  ╔═══════════════════════════════════════════════╗
  ║  AsentumChain — post-quantum L1 blockchain    ║
  ╚═══════════════════════════════════════════════╝

  RPC: http://127.0.0.1:8545

  Current account: default
  Address:         0x3c2EFa568F952ce8a1A53C87c25D32aCf53ec48A

  Try:
    asentum balance            show your balance
    asentum send 10 <address>  send ASE
    asentum chain              show chain state (height, latest block)
    asentum help               full command reference

It knows where you are in the journey. First-time user → quickstart. Returning user → suggests the three commands they'll actually want.

the config file

No more env vars. There's a new ~/.asentum/cli/config.json with two fields: rpcUrl and currentAccount. Set them once with asentum config set rpc https://your-testnet.example and you never think about it again. The env var still works (it overrides the config) but nobody has to know that.

Side benefit: commands that need an account now default to the current one. asentum balance with no args shows your current-account balance. asentum use bob switches. No more --from alice on every command.

the friendly error handler

The other half of "noob-friendly" is how errors look. The old bin.ts was:

main(argv).catch(err => {
  console.error(`error: ${err.message}`);
  process.exit(1);
});

So a Windows user running asentum chain with no testnet running got:

error: fetch failed

Thanks, that's useless. The new version inspects the error and prints a custom explanation:

✗ Could not reach the AsentumChain RPC.

  The node at your configured RPC URL is either not running
  or not reachable from your machine.

  Try one of:
    asentum config                    (see which URL you're pointing at)
    asentum config set rpc <url>      (change it to the public testnet)
    asentum config set rpc http://127.0.0.1:8545  (use a local node)

Same for "account 'x' not found" (points at asentum account list + asentum account new), "unknown command" (points at asentum help), etc. Stack traces are gone for the common cases. Noobs see actionable next commands.

INSTALL.md

The last piece. A 200-line install guide with separate Windows and macOS sections, step-by-step, expected-output-verbatim, and a troubleshooting section covering the six things most likely to go wrong for a first-timer:

1. asentum not recognized after install (PATH issue, reopen terminal)
2. "Could not reach RPC" (config URL fix)
3. permission denied on npm install -g (sudo or npm prefix fix)
4. Already-exists account on quickstart (totally fine, use it)
5. Rate-limited faucet (wait 60 seconds)
6. node: command not found (installer updated PATH but your session doesn't know, reopen terminal)

The full file opens with:

"A step-by-step for getting asentum working on your computer, even if you've never touched a terminal before."

And closes with:

"Questions, bugs, feedback? Open an issue or message the person who sent you the testnet link. I want to make this as noob-proof as possible — if something confused you, tell me."

That's the vibe. This isn't for crypto devs. This is for the friend who's never done any of this, and who's going to close the tab the moment they see a stack trace.

the score

10 new CLI tests (config module end-to-end, round-trip, env override precedence, corruption handling, missing-fields fallback). 273 tests total across all packages. Live smoke test confirms the full quickstart flow works end-to-end against a real running node. The CLI builds clean, types clean.

Phase 5 rollout sequence:

• ✅ testnet reachable from a browser (5.1 + 5.2)
• ✅ basic wallet via CLI (5.3 ← this)
• ⬜ lightweight validator client (5.4 — the one that actually proves the decentralization thesis)

Phase 5.4 is the headline deliverable. I want a friend to be able to download a binary, run one command, and join the validator set. That's where this is going next.

— milkie