Nodion CLI Introduction

Manage your Nodion applications from the terminal. Built for humans and AI coding agents.

The nodion CLI is a Go binary that talks to the public REST API under https://api.nodion.com/v1/. It ships with first-class support for AI agents like Claude Code, OpenAI Codex and Gemini CLI: a repo-local nodion.yml pins a directory to a specific project and application, so agents can run nodion deploy --wait without guessing IDs.

Install

macOS & Linux

bashcurl -fsSL https://cli.nodion.com/install.sh | bash

The script detects your OS and architecture, fetches the matching release, drops the binary on your PATH (default /usr/local/bin, falls back to ~/.local/bin) and makes it executable. Redirect the target with NODION_INSTALL_DIR=~/bin.

Windows (PowerShell)

powershellirm https://cli.nodion.com/install.ps1 | iex

Installs to %LocalAppData%\Programs\nodion and adds that folder to your user PATH. No admin rights required. Override with $env:NODION_INSTALL_DIR='C:\Tools\nodion'.

Direct download

Pre-built archives for every supported platform live at:

• macOS (universal: arm64 + x86_64)
• Windows (64-bit .zip)
• Linux (64-bit .tar.gz)

Quickstart

bashnodion login
cd my-app
nodion link              # pins this directory to a Nodion project + app
nodion deploy --wait     # streams build/release logs until available
nodion env set FOO=bar
nodion status

Authentication

Running nodion login opens a browser-based device flow:

1. The CLI creates a one-off login token on the server.
2. Your browser opens https://my.nodion.com/auth/cli/<token>.
3. Once you confirm the login in the dashboard, the token is exchanged for a long-lived User API Key.
4. The key is stored in ~/.config/nodion/config.yml with 0600 permissions.

The token carries whatever scopes you granted it in the dashboard (User Settings → Security). See the Authentication API docs for the full scope matrix.

For CI or non-interactive usage, skip nodion login entirely and pass the token via env var:

bashexport NODION_API_TOKEN=nk_live_...
nodion apps list

Project linking (nodion.yml)

Once a directory is linked, every app-scoped command resolves project and app automatically. Two ways to link:

bash# Pick an existing app interactively (or with flags)
nodion link
nodion link --project prod --app my-api

# Create a new app; nodion.yml is written on success
nodion apps create --name my-api --strategy prebuilt_image \
  --region eu-west-1 --instance-type t2-small \
  --image-name myorg/my-api --image-tag latest

The resulting nodion.yml is tiny and safe to check into git. The IDs are UUIDs, not secrets:

yamlversion: 1
project:
  id: 550e8400-e29b-41d4-a716-446655440000
  name: nodion-prod
app:
  id: 7f3b2a1c-9e4d-4f6a-b8c2-1a2b3c4d5e6f
  name: my-api

Resolution order for project and app IDs:

1. --app / --project flag
2. NODION_APP_ID / NODION_PROJECT_ID env vars
3. nodion.yml (searched from cwd walking up)
4. Active project from the global config (only for commands that don't need an app)

Common commands

bash# Applications
nodion apps list
nodion apps get                # shows the linked app
nodion apps create ...

# Deployments
nodion deploy --wait           # streams logs until terminal state
nodion deploy --last --wait    # redeploy the most recent deployment
nodion deployments list
nodion deployments logs --follow  # tails the latest deployment's logs

# Environment variables
nodion env list
nodion env set KEY=value
nodion env unset KEY

# Custom domains
nodion domains add my-app.example.com
nodion domains verify <domain-id>

# Introspection
nodion status                  # what is this repo linked to?
nodion whoami

JSON output

Every list / get command supports --output json, making the CLI useful as a scripting primitive:

bashnodion apps list --output json | jq '.[] | .name'

Exit codes

• 0: success
• 1: generic failure
• 2: authentication problem (expired or missing token)
• 3: API returned a non-2xx response
• 4: timeout (e.g. deploy --wait-timeout elapsed)

Environment variables

• NODION_API_URL: override the API base URL (default https://api.nodion.com)
• NODION_API_TOKEN: bypass the config file for the token
• NODION_PROJECT_ID: override the active project
• NODION_APP_ID: override the linked application
• NODION_CONFIG: path to the global config file
• NO_COLOR: disable ANSI colors

Next steps

• Explore the full API reference for every endpoint the CLI talks to.
• Want to drive Nodion from inside an AI agent instead? Check the MCP docs.
• New features and fixes ship on the Changelog.