Singularity CLI reference

Use singularity or its sing alias for the public CLI. Both names run the same entrypoint from @0xsingularity/cli. This reference describes the 0.4.0 source interface and identifies features absent from the 0.3.0 npm release rechecked on 8 September 2026. Use CLI and wallet setup, program compatibility checks, or transaction inspection for ordered tasks.

The Rust eto-cli binary is a distinct utility with different configuration, amount parsing and transaction builders. Its commands are documented separately below. Neither CLI name is the production node executable, svm-vm.

Installation and version selection

To select the checked public package version for a global installation:

npm install --global @0xsingularity/cli@0.3.0
singularity version
singularity help

The published version prints 0.3.0. The source package and its version command identify 0.4.0, including raw rpc and namespace commands that the tested published release rejects as unknown. Do not infer package publication from a changed source manifest.

The package declares Node.js 18 or newer, but the resolved Ink dependency in the inspected installation requires Node.js 20 or newer. Checks here used Node.js 22.22.2. Use a dependency-compatible Node version; the package's minimum declaration alone is insufficient. The source 0.4.0 package also depends on SDK ^0.3.0, while the npm SDK latest observed in this run was 0.2.0. A fresh source installation is therefore not established by the successful public CLI install.

For checkout access, the existing built entrypoint can be inspected with:

node sdk/singularity-cli/dist/cli.js version
node sdk/singularity-cli/dist/cli.js help

Those paths were present and exercised in this workspace. They are not a guarantee that a fresh clone includes built output. Source contracts: package manifest, version/help.

Invocation and parser rules

singularity [OPTIONS] COMMAND [ARGUMENTS] [OPTIONS]
singularity

No command starts the guided terminal app only when both stdin and stdout are terminals. In a pipe or noninteractive runner it prints an explanation and exits 1.

Options may appear before or after the command. Repeated value options use the last value. Value options accept either --name VALUE or --name=VALUE; boolean switches do not accept =true or =false. Empty endpoint or wallet flag values fall through during configuration resolution. The parser has no -- end-of-options delimiter. Negative numeric positional arguments reach amount validation rather than becoming unknown flags.

Top-level --help/-h and --version/-V are translated into positional command names. They are not universal nested-command overrides. Prefer singularity help, singularity node help, or singularity validator help; do not assume singularity transfer --help displays transfer-specific help. See the parser.

Options are globally parsed, but each command consumes only its relevant fields. For example, balance --json does not become a JSON balance API. Raw RPC results are JSON without needing that switch.

Configuration and keys

Endpoint and wallet resolution is:

1. Nonempty command-line flag.
2. Nonempty SINGULARITY_RPC or SINGULARITY_WALLET.
3. Saved endpoint or walletPath in ~/.config/singularity/settings.json.
4. SDK public endpoint https://rpc.entropytoorder.xyz or wallet ~/.config/singularity/id.json.

Malformed, missing or unreadable settings are treated as empty settings. A typo can therefore select a fallback endpoint instead of producing a configuration error. doctor reports the selected values and their origins. Save settings through the guided app's Settings screen; there is no public singularity config set command. See configuration resolution.

The wallet is an Ed25519 keypair stored as a 64-byte JSON array. New wallet creation uses restrictive permissions and refuses replacement without --force. wallet show prints only the public address; wallet path prints the path without requiring the key to exist. Treat the file as the signing secret and back it up before using the wallet.

Node consensus identity is separate: the managed layout uses ~/.config/singularity/node/keys/consensus.key. The wallet pays or bonds funds; the consensus key identifies the validator. A saved endpoint, a wallet address and a consensus identity are three different settings.

Wallet and transaction commands

All public CLI amounts are SING, including whole numbers. One SING is one billion lamports. Amount parsing requires a finite positive decimal and rejects negative, zero, exponent notation and values that round below one lamport.

The transfer precheck budgets a fixed 5,450 lamports above the amount. This is a CLI assumption, not a live fee quotation or assurance that every transaction costs that amount. The transfer helper sends once and polls signature status every 100 ms for up to 30 seconds. It rejects on-chain errors and waits for confirmed or finalized. On timeout, it returns the signature and tells the reader to inspect it later. Do not create a second payment merely because this deadline elapsed.

A tx lookup of a failed on-chain transaction exits 0 because the lookup succeeded; read its status failed output. Similarly, doctor returns a diagnostic report with exit 0 even when the endpoint or wallet is unavailable. Neither is a health-check exit-code API. See command output and confirmation.

Program checks and deployment

check-program FILE is an offline ELF compatibility screen. It verifies the file and supported ELF machine/flags shape, including the accepted sBPF forms. It is not complete bytecode verification, an execution test, or a proof that the target node supports the program's syscalls.

deploy FILE [--yes] runs that check before the toolchain or network work. If a managed toolchain is absent, noninteractive installation needs --yes. The deployment then invokes the Solana-compatible program deployment tool against the selected endpoint and wallet, with --use-rpc, --skip-feature-verify and --max-sign-attempts 1000. These are wrapper-selected options, not additional public parser options.

A rejected file prints FAIL plus reasons and exits 1. A deployment failure includes captured toolchain output; a success prints the program identifier when available. Actual deployment requires a funded wallet, compatible loader and working node. See ELF validation and deployment wrapper.

Node and validator commands

The managed node directory defaults to ~/.config/singularity/node. It contains node.json, runtime binaries/libraries, config/node.toml, genesis, environment configuration, identity keys, data and logs. The managed service is singularity-node, distinct from the AWS fleet's eto-node.

consensus maps to runtime role validator and requires the GPU execution path. Both replica and cpu map to readonly; CPU mode is not a CPU consensus validator. The default join bond and minimum are 100 SING. The join precheck also leaves 0.01 SING beyond the bond as a fee cushion.

Join and leave return after submission and print intended transition messages; they do not poll for finalized registry execution. A submission signature alone does not establish Pending, Active or completed withdrawal of a bond. Deployment support and epoch transitions must be verified independently in validator lifecycle and state sync. Source: node commands, mode mapping.

Despite older help text promising guided selection without --yes, the inspected command dispatch calls initialization directly once mode validation passes. Start the no-command terminal app for guided setup. Node initialization can download artifacts, build a CPU runtime, create configuration and keys, or prepare a container/service. It is a setup operation, not a harmless way to discover whether releases exist.

Raw RPC and namespaces: source 0.4.0

singularity rpc getVersion
singularity rpc getBlock 123 '{"transactionDetails":"none"}'
singularity evm block-number
singularity hilsa chain-catalog
singularity onebook list

These examples require a CLI version with the raw surface. Each parameter token is parsed as JSON when possible and otherwise passed as a string. Shell-quote objects and arrays. A JSON string such as '"123"' preserves a number-looking identifier as a string.

The CLI always assembles positional array params. Passing one object token sends params: [{...}], not params: {...}. That distinction matters for HILSA handlers expecting a top-level object. Use a direct JSON-RPC request for such methods unless the handler explicitly accepts the one-element-array form. The HILSA interface reference specifies those shapes.

Namespace groups are svm, evm, explorer, wasm, move, admin, hilsa, cil, token, onebook, workflow, crossvm and agent. Each accepts its friendly kebab-case method, SDK property name or wire name, case-insensitively. Bare namespace, list or help prints the bundled manifest.

Bombil is the product name; onebook remains the exact CLI namespace. See Bombil names and activation contracts for the complete mapping. A local listing of fifteen methods proves only what the bundled SDK manifest knows. It does not probe the server or establish Bombil dispatch availability. The generic admin group likewise supplies no automatic administrator credential.

Results are pretty-printed JSON values, without the outer JSON-RPC envelope. RPC failures go to stderr and exit 1. See raw dispatch.

Errors and executed checks

Executed checks used a separately installed CLI 0.3.0 and the existing source build reporting 0.4.0. Version/help and wallet-path commands passed. Disposable wallet creation produced a 64-byte JSON key with mode 0600; public-address display passed and repeat creation was refused. Unknown options, negative amounts, noninteractive no-command invocation and invalid program input failed as expected. The source build listed Bombil's legacy namespace and surfaced the public RPC health error; the published build rejected the newer rpc command. No funded transfer, program deployment, node initialization or validator registration was executed.

Fresh isolated checks on 8 September 2026 repeated wallet creation/display and overwrite refusal, the published raw-command rejection, program-header acceptance/rejection and transaction lookup against a local mock. The failed-transaction mock exited 0 and printed failure status; missing lookup exited 1. These checks exercise the client, not live execution.

Distinct Rust utility: eto-cli

The Rust utility lives in runtime/src/bin/eto_cli.rs and prints version 1.0.0 in help. Its help uses eto in example usage, but the Cargo binary is eto-cli. Do not copy its options into singularity.

Several source limitations make this utility unsuitable as the public deployment tutorial. The global parser consumes --url before config set sees it, so the advertised persistent setter does not receive its documented option. Prefer an explicit per-invocation endpoint rather than assuming that command saved it.

Its transfer and demonstration builders embed placeholder recent blockhashes rather than fetching a current one. The EVM “deploy” handler builds an account-creation transaction; it does not install and execute the supplied bytecode through a complete deployment flow. WASM deployment and Move deployment explicitly return unsupported/not-implemented errors. The latter is a CLI encoder gap, not proof that the Move runtime lacks publication.

These are source-inspected limits, not executed Rust-binary checks. The useful public workflow remains the Singularity CLI guide. Rust evidence: configuration and keys, amount and transfer builder, parser and setter, deployment handlers.