opentela-cli

A Node.js CLI for OpenTela — sign in to the account console, spin up nodes with an interactive wizard, and check the network.

npm install
npm link          # puts `opentela` on your PATH (or run `node bin/opentela.js`)

Requires Node 18+.

Commands

opentela login

Signs in (or signs up) against the same Neon Auth deployment the cloud.opentel.ai console uses. Email verification (6-digit OTP) is handled inline when an address isn't verified yet.

opentela wallet bind reuses this session, so opentela login first to bind without retyping your password.

The session cookie is stored at ~/.config/opentela/cli.json (mode 0600), so it is reused by later commands. See also opentela whoami and opentela logout.

opentela login            # sign in or create an account
opentela login --signup   # straight to account creation
opentela whoami           # show account + session/JWT validity

opentela up

Interactive wizard that:

1. Locates the otela binary (or offers to download the latest GitHub release into ~/.config/opentela/bin).
2. Lets you pick a wallet — it reads every wallet already managed by otela (~/.config/opentela/accounts/*/keypair.json), or creates one via otela init, imports one, or accepts an address you type.
3. Lets you choose a role:
   • Head node — --mode standalone, auto-detected public address, deterministic seed 0.
   • Worker node — join either the public OpenTela network (bootstraps.opentela.ai) or a custom head multiaddr (/ip4/<addr>/tcp/43905/p2p/<peerId>), optionally serving a model via Docker (baked-in: SGLang, vLLM, Ollama). The CLI turns the choice into the docker run … --subprocess string from the Docker tutorial.
4. Stores the configuration as a profile in ~/.config/opentela/cli.json and points cfg.yaml's account.wallet at the chosen keypair.
5. Starts the node in the foreground, or detached with --background (logs land in ~/.config/opentela/logs/).

opentela up             # interactive wizard
opentela up --saved     # restart from the stored config, no questions
opentela up -c node.yaml # start from a YAML file, no prompts (see below)
opentela stop           # stop a background-started node

Non-interactive config file (-c, --config)

opentela up -c node.yaml reads the entire node configuration from a YAML file and starts it with no prompts — everything the wizard would ask is spelled out in the file, so it works in scripts and CI. --dry-run validates the file and prints the exact otela start … command without starting or saving anything.

The file maps 1:1 onto the profile the wizard stores in cli.json, so the same buildStartArgs runs it and opentela up --saved / opentela stop work afterwards (the profile is saved under --profile, default default). If the wallet is one otela manages locally, cfg.yaml's account.wallet is pointed at it just like the interactive flow.

# node.yaml — a worker serving a model with Docker
role: worker                      # 'head' or 'worker' (required)
wallet: 5YNmS1R9nNSCzzBxXKhTj9Q8KQxqpmCCW5jvFKq5XnQq   # omit to use the otela default
seed: "1"                         # omit for a random peer ID
bootstrapAddr: /ip4/1.2.3.4/tcp/43905/p2p/Qm…        # omit to join the public network

service:                          # optional; workers only
  engine: sglang                  # sglang | vllm | ollama (or give `command:`)
  model: Qwen/Qwen3-8B            # HF id (sglang/vllm) or Ollama tag
  port: 30000                     # defaults to the engine's standard port
  gpus: all                       # all | none | { device: 2 }
  withHfToken: true               # pass $HF_TOKEN from the environment
  extraArgs: --max-model-len 16384 --trust-remote-code
  # — or, instead of engine+model, supply the whole command —
  # command: docker run --rm --gpus all --network host ollama/ollama:latest ollama serve
  # name: llm

A head node only needs role, publicAddr (required), and optionally seed (defaults to 0):

role: head
publicAddr: 203.0.113.10
seed: "0"

opentela up -c node.yaml             # start in the foreground
opentela up -c node.yaml --background # start detached (logs to ~/.config/opentela/logs)
opentela up -c node.yaml --dry-run    # validate + print the command, start nothing

Serving a model with Docker (worker)

When the wizard asks whether to serve a model, the CLI builds a docker run --rm --gpus all --network host … command for one of SGLang, vLLM, or Ollama, as described in the Docker tutorial, and hands it to otela start --subprocess so OpenTela launches and supervises the container like any other subprocess.

• GPU — all GPUs (--gpus all, needs the NVIDIA Container Toolkit), a single GPU (--gpus device=N), or CPU only (no --gpus).
• Hugging Face cache (SGLang/vLLM) — mounted from ~/.cache/huggingface so models aren't re-downloaded each run.
• Hugging Face token (SGLang/vLLM) — the command references $HF_TOKEN, so the token is read from your environment at launch time and is never written into cli.json or the logs. Provide it inline when prompted, or export it (export HF_TOKEN=hf_…) for --saved runs.
• Ollama — models persist in the opentela-ollama Docker volume and are pulled on first request.

opentela wallet

Lists the Solana wallets otela manages on this machine (the first is the default used by otela start) and shows how to bind one to your OpenTela account. Your "opentela address" is the base58 public key of that wallet.

Binding links a wallet to your account at cloud.opentel.ai so every peer your nodes claim is owned by the account and the faucet can pay OTELA to it. One account operates a single wallet. The handshake signs a server-issued challenge with the wallet's private key — the key never leaves the machine.

opentela wallet          # list local wallets + how to bind (same as 'wallet list')
opentela wallet bind     # bind the default wallet
                         #   reuses your `opentela login`, or asks for email + password
opentela wallet bind --token <jwt>            # bind with a Neon Auth JWT directly
otela wallet link --email [email protected]     # same flow from the otela binary itself

If you already hold the wallet in Phantom (not locally), export it (Settings → Export Private Key), save the 64-byte key as a JSON integer array, and run otela wallet import <keypair.json> before binding. See also otela init to create a fresh wallet.

opentela status

opentela status                              # API health + public service catalogue + local peer table
opentela status --node http://<addr>:8092    # peer table from a specific node

• Gateway health: GET https://api.opentela.ai/healthz
• Public service catalogue: GET https://api.opentela.ai/v1/services (services, models, online/provider counts — no API key needed)
• Peer table: GET <node>/v1/dnt/table (probes a local node at 127.0.0.1:8092 automatically when one is running)

opentela config

Prints the stored CLI state (session token redacted).

Environment overrides

| Variable | Default | Purpose | |----------|---------|---------| | OTELA_BIN | autodetected | path to the otela binary | | OPENTELA_HOME | ~/.config/opentela | runtime/config directory | | OPENTELA_NEON_AUTH_URL | production Neon Auth URL | sign-in server | | OPENTELA_API_BASE_URL | https://api.opentela.ai | gateway for status | | OPENTELA_AUTH_ORIGIN | https://cloud.opentela.ai | trusted origin sent on sign-in POSTs | | HF_TOKEN | unset | Hugging Face token for gated models, passed to SGLang/vLLM Docker containers at launch |