Configure the Singularity CLI and wallet

Install a known public CLI, select the wallet file you intend to use, and choose an endpoint explicitly. You will finish with a reloadable local wallet and a clear distinction between successful local setup and a healthy network connection.

Starting point: Node 20 or newer, npm, a shell and a new working directory. Use an existing wallet only when you know its path and have a private backup. For a guided signing lesson that needs no network or funds, start with the offline quickstart.

The public package is @0xsingularity/cli, with equivalent executable names singularity and sing. It is distinct from the Rust operator binary eto-cli. See the command reference for exact arguments and the operator interface.

Install a known version

The registry recheck at 2026-09-08 01:42 UTC found CLI 0.3.0, while this checkout's CLI source and existing local build report 0.4.0. Version 0.4.0 adds the raw rpc and namespace command surface and depends on SDK 0.3.x; that SDK version was absent from the checked public registry. Do not assume the current source is installable by asking npm for its version. Published CLI metadata, source manifest.

Use Node 20 or newer; Node 22.22.2 was used for the checks below. Although the package declares Node 18+, the resolved Ink 6.8.0 dependency requires Node 20+. A directory-local installation avoids changing your global executable selection:

npm install --prefix ./singularity-tools --ignore-scripts --no-audit --no-fund --save-exact @0xsingularity/cli@0.3.0
CLI=./singularity-tools/node_modules/.bin/singularity
"$CLI" version
"$CLI" help

Expected version:

0.3.0

The installation and command checks succeeded on the documentation host. The checked package resolved its own SDK dependency to 0.1.1; installing SDK 0.2.0 separately does not upgrade that nested dependency. Pinning the CLI version does not freeze all transitive dependencies; retain the generated lockfile when reproducibility matters.

Run "$CLI" in an actual terminal for the guided app. Redirected input or output produces exit code 1 and:

The guided app needs a terminal. Run singularity help for the commands.

For scripts, use explicit commands. Entrypoint behavior.

Create a wallet you can identify and recover

Use an explicit new file for this exercise:

WALLET=./singularity-demo/id.json
"$CLI" wallet path --wallet "$WALLET"
"$CLI" wallet new --wallet "$WALLET"
"$CLI" wallet show --wallet "$WALLET"

wallet new prints a base58 address and the saved path. wallet show prints only the address, making it suitable for shell capture:

ADDRESS=$("$CLI" wallet show --wallet "$WALLET")

Creation does not create a funded on-chain account. A fresh key can exist locally while account lookup reports that no account exists on chain.

The file is an unencrypted JSON array of 64 secret-key bytes in the Solana-compatible format. It is not a mnemonic phrase, browser wallet or hardware-wallet connection. The writer uses a fresh temporary file, mode 0600 and rename; the loader checks array length and byte values before reconstructing the keypair. Back up the file privately. Do not put it in source control or paste its contents into diagnostics. Wallet format and persistence.

Creating a wallet at an existing path fails by default. --force replaces that key file; it does not recover the previous key or move its funds. A fresh check at 2026-09-08 01:49 UTC created and reloaded the same public address, wrote 64 bytes with permission 0600 and rejected an accidental second creation. Wallet commands.

Select the endpoint deliberately

Both the endpoint and wallet follow this precedence, from highest to lowest:

1. A nonempty command-line flag.
2. SINGULARITY_RPC or SINGULARITY_WALLET.
3. endpoint or walletPath in ~/.config/singularity/settings.json.
4. Built-in defaults: https://rpc.entropytoorder.xyz and ~/.config/singularity/id.json.

For example:

RPC=https://rpc.entropytoorder.xyz
"$CLI" account "$ADDRESS" --endpoint "$RPC"
"$CLI" balance "$ADDRESS" --endpoint "$RPC"

An earlier endpoint check with the published CLI and a fresh address reported “This account does not exist on chain.” That response distinguishes a keypair from an initialized account. The later upstream error recorded below prevented a current successful lookup; do not expect the earlier response from an unavailable endpoint.

doctor reports the chosen endpoint and wallet together with their configuration sources, toolchain status and node information. It is diagnostic text and can exit successfully while reporting an unreachable endpoint. Read the findings rather than treating code 0 as a healthy-node certificate. Invalid or unreadable saved settings fall back to an empty settings object, so a mistyped settings file can silently expose lower-precedence defaults. Configuration resolution, doctor output.

Check health before a live transfer

Wallet creation and address lookup do not establish that an endpoint can process a payment. With CLI 0.3.0, use direct JSON-RPC for the health check:

curl --silent --show-error --max-time 15 "$RPC" \
  -H 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"getHealth","params":[]}'

A healthy service returns "result":"ok". HTTP 200 can contain a JSON-RPC error, so inspect the body. Also check the version and genesis identity using the endpoint readiness steps before relying on a live network.

At 2026-09-08 01:44 UTC, the sampled public endpoint returned -32000, Upstream error (HTTP 521). Earlier checks found a halted persistence drain while account reads still answered. These are dated deployment observations in the availability reference, not failures of local wallet creation. No faucet request, transfer or deployment was performed for these checks.

If the endpoint is unavailable, keep the wallet setup and resolve the service separately. Do not recreate a wallet or overwrite its key to repair an RPC error.

Confirm setup and choose the next task

Setup is complete when the pinned executable reports its version, wallet show reloads the expected address, and the explicit wallet/endpoint selections match your intent. A live account check additionally needs the intended endpoint to respond. Record an unavailable endpoint separately from completed local setup.

The public CLI opens its guided app only when run without a command in a real terminal. In scripts, use explicit commands. The source-only rpc command is absent from the checked npm 0.3.0 release; a fresh test returned Unknown command "rpc". Existing onebook names continue to refer to Bombil in newer source interfaces; do not guess replacement bombil_* commands.

The fresh Linux checks used Node 22.22.2 and npm 9.2.0. Installation, version, wallet path/create/show, overwrite refusal, unknown-command rejection and nonterminal rejection were executed. Configuration precedence and current source interface distinctions were checked against their implementations. Live payment and program execution are separate tasks with separate evidence.