Nodit CLI

A Go CLI for Nodit developers. Server endpoints are injected at build time. It covers both the OAuth-based Management API and the API Key-based Product APIs.

• OAuth login, and management of projects, API Keys, allowlists and CU usage
• The bundled catalog of networks and the products each one supports
• Web3 Data API and multichain entity lookups
• Single JSON-RPC calls against Node
• REST Node APIs for Aptos, Cosmos SDK and Tron chains
• Classic and Flexible webhook management
• Classic ADDRESS_ACTIVITY address lists
• Watching Nodit Stream over a websocket
• YAML, JSON, JSONL and TOON output

RPC batching, the Node websocket rpc watch, the Aptos Indexer GraphQL indexer query, webhook verify and Stream over gRPC are out of scope for this release.

Products differ per network. Run nodit network list --product <product> to see which.

curl -fsSL https://raw.githubusercontent.com/noditlabs/nodit-cli/main/scripts/install.sh | sh

With wget instead of curl:

wget -qO- https://raw.githubusercontent.com/noditlabs/nodit-cli/main/scripts/install.sh | sh

irm https://raw.githubusercontent.com/noditlabs/nodit-cli/main/scripts/install.ps1 | iex

go install github.com/noditlabs/nodit-cli/cmd/nodit@latest

It builds from source rather than fetching a release, so nothing is checksum-verified here beyond what the Go module proxy already guarantees, and the binary lands in $(go env GOBIN), or $(go env GOPATH)/bin when that is empty.

Open a new terminal so the updated PATH applies, then:

nodit version

The installer prints the setup for your shell, and nodit completion --help covers all four. It is a few lines to run once, because a shell loads completions only from where it already looks.

It downloads the archive for your platform and checks it against the release checksums.txt, refusing to install on a mismatch. That catches a truncated or corrupted download. It is not a signature: the checksums come from the same release as the archive.

The binary is put in place by rename, so a running nodit keeps working and a failed download leaves nothing half-written. The install directory is added to your shell startup file, or to the user PATH on Windows, unless NODIT_NO_MODIFY_PATH=1 is set.

The downloaded binary is run once before it replaces anything, so a build that cannot start on this machine fails the install instead of taking out a working one.

Rerunning it upgrades in place, without stacking duplicate PATH entries:

Updated nodit v0.1.0 -> v0.2.0 at /Users/you/.local/bin/nodit

The version comes from the binary that was just installed, not from the tag that was asked for.

The variables go on sh, the side of the pipe that runs the installer:

curl -fsSL https://raw.githubusercontent.com/noditlabs/nodit-cli/main/scripts/install.sh |
  NODIT_VERSION=v0.1.0 NODIT_INSTALL_DIR="$HOME/bin" sh

To read the script before running it:

curl -fsSL -o install.sh https://raw.githubusercontent.com/noditlabs/nodit-cli/main/scripts/install.sh
less install.sh && sh install.sh

Published targets are linux/amd64, darwin/amd64, darwin/arm64 and windows/amd64. Archives and checksums are on the releases page. For any other platform, build from source as described below.

On macOS, install with the script above or with Go. The macOS builds are not notarized yet, so a copy downloaded through a browser is refused by Gatekeeper.

Log out first, while the binary is still there. It removes the saved login and the API Keys linked by project select from the credential store:

nodit auth logout

If it reports CREDENTIAL_STORE_UNAVAILABLE on a machine where you never ran nodit auth login or nodit project select, nothing was stored there, so go on.

Then delete the settings directory. It holds the config, and the encrypted credential file when the OS credential store was not available. nodit config path prints a file inside it.

Then the binary, from NODIT_INSTALL_DIR if you set one, or from where go install put it:

rm ~/.local/bin/nodit

Last, remove the two lines the installer added to your shell startup file: the # added by nodit-cli installer marker and the PATH line under it. This shows where they are, and works in zsh, bash and fish. If you set ZDOTDIR, the zsh file is $ZDOTDIR/.zshrc instead.

grep -n 'added by nodit-cli installer' ~/.zshrc ~/.bashrc ~/.bash_profile ~/.config/fish/config.fish 2>/dev/null

fish also keeps the directory in the universal fish_user_paths, so removing the lines is not enough there. Run this once in fish, with your NODIT_INSTALL_DIR in place of ~/.local/bin if you set one:

set -U fish_user_paths (string match -v -- ~/.local/bin $fish_user_paths)

If you set up tab completion, also delete the file you wrote, ~/.zfunc/_nodit, ~/.bash_completion.d/nodit or ~/.config/fish/completions/nodit.fish, and the source or fpath line you added for it.

On Windows, delete nodit.exe, and any nodit.exe.old left by an upgrade that ran while nodit was open, from %LOCALAPPDATA%\Nodit\bin or your NODIT_INSTALL_DIR, and drop that directory from the user PATH. With the default location, deleting %LOCALAPPDATA%\Nodit removes both files. If you set up tab completion, also remove the nodit completion powershell line from your $PROFILE.

There are two credentials, and which you need depends on what you call.

auth login opens a browser for OAuth with PKCE S256 and a loopback callback. project select then links one active API Key to that project, so the product commands work with no further setup.

nodit auth login
nodit project list
nodit project select <project-id>

If the project has more than one active API Key, project select stops and lists them, because picking one for you would silently decide which key the calls are billed against:

nodit project select <project-id> --key-id <key-id>

Confirm what is in place. It prints where each credential comes from, never the secret itself:

nodit auth status

Skip the login when you only call the product APIs:

export NODIT_API_KEY=<your-api-key>

$env:NODIT_API_KEY = '<your-api-key>'

The API Key is resolved in this order.

1. --api-key
2. NODIT_API_KEY
3. the API Key linked by project select

API Keys and OAuth tokens never go in the plain config file. The OS credential store is used when available (Keychain, libsecret, Credential Manager), otherwise they are written to an AES-256-GCM encrypted file. Both are keyed per endpoint set, so builds against different environments never read each other's credentials. nodit config path prints the config location.

Pass --no-interactive to fail instead of opening a browser or prompting, and supply the key through NODIT_API_KEY or --api-key. Management API commands need an OAuth login, which is interactive by design, so unattended usage is limited to the product APIs.

mkdir -p ~/.zfunc && nodit completion zsh > ~/.zfunc/_nodit                           # zsh
mkdir -p ~/.bash_completion.d && nodit completion bash > ~/.bash_completion.d/nodit    # bash
mkdir -p ~/.config/fish/completions && nodit completion fish > ~/.config/fish/completions/nodit.fish
nodit completion powershell | Out-String | Invoke-Expression                           # PowerShell

zsh then needs fpath=(~/.zfunc $fpath) and autoload -Uz compinit && compinit in ~/.zshrc, and bash needs source ~/.bash_completion.d/nodit in ~/.bashrc, or ~/.bash_profile on macOS. PowerShell loads it for the current session; add the same line to $PROFILE to keep it.

Network IDs complete from the catalog in the binary, filtered by what the command can reach, so nodit stream watch --network <tab> offers only networks carrying Stream. nodit completion --help covers the per-shell details.

nodit network list
nodit network list --product node
nodit config set network ethereum-mainnet
nodit config set output json

nodit data native balance \
  --network ethereum-mainnet \
  --address 0x000000000000000000000000000000000000dEaD

nodit rpc eth_getBalance \
  0x000000000000000000000000000000000000dEaD latest \
  --network ethereum-mainnet
nodit rest GET /accounts/0x1 --network aptos-mainnet

The output format is taken from --output, then the saved output setting, then YAML. It does not change between a terminal, a pipe and a redirect.

Success is written to data on stdout and failure to error on stderr. An error carries code, message and whatever optional metadata the server supplied.

Requires Go 1.27.1.

go build ./cmd/nodit

That is enough: the endpoints default to the public service. They are fixed at build time and have no runtime override, so a binary cannot be pointed at another server by its environment.

A build for a different deployment overrides all three through the linker, which is what scripts/build-dist.sh does for releases:

AUTH_ISSUER=https://auth.example.com \
API_RESOURCE=https://api.example.com \
PRODUCT_DOMAIN=example.com \
make build

The binary lands in bin/nodit.

A malformed value exits with INVALID_BUILD before any command runs.

nodit version reports the release tag on an installed build, the module version on a go install, and unreleased when neither is available.

make test

CI checks formatting, the race detector, vet, static analysis, dependency vulnerabilities, and the macOS, Linux and Windows builds. A change to externally visible behaviour updates the command help and the documentation with it.

Issues and pull requests are closed on this repository. Send bug reports, security reports and questions to developers@lambda256.io.

This project is licensed under the Apache License 2.0. Refer to the LICENSE file for full license terms. Relevant legal notices are provided in the NOTICE file.

"Nodit" and the Nodit logo are trademarks of Lambda256. Use of the name or logo without prior written permission is prohibited.

© Lambda256. All rights reserved.