CLI Tool

The Nebion CLI lets you access your environments from the terminal — SSH into containers, view logs, manage environment variables, deploy environments, and open environment URLs.

$ nebioncli hub

⚡ Nebion CLI | Org: ACME Corp | Website

Projects

Website (8) x1

API Backend v5

Mobile App (3) x1

Docs (1)

Staging (1)

Environments — Website

Title	Status	Branch	Deploy
pr-87	ERROR	feature/auth	1h
pr-86	SUCCESS	nebion-routes	1d
pr-85	SUCCESS	fix/nav-links	3d
pr-82	SUCCESS	redesign	5d
pr-79	SUCCESS	feature/search	7d
dev	SUCCESS	dev	7d

fix/nav-links pr-85

Branch: fix/nav-links Author: Jane Doe URL: pr-85.website.com

tab panel s ssh l logs u url / filter ? help

$ nebioncli ssh -p mysite -e 42 -c php
  Connected to pr-42.mysite.com (php)
  web@pr-42:~$

$ nebioncli doctor
  ✓ .nebion.yml         valid
  ✓ Docker Compose      valid
  ✓ Routing             configured
  ✓ All checks passed

$ nebioncli logs -f
  [nginx] GET /api/users → 200 (12ms)
  [php]   Cache cleared successfully

Install

Linux / macOSManual Download

bash

curl -fsSL https://nebion.wsagency.io/sites/default/files/cli/install | bash

bash

# Download the binary for your platform:
#   nebioncli-linux-amd64    (Linux x86_64)
#   nebioncli-linux-arm64    (Linux ARM64)
#   nebioncli-darwin-amd64   (macOS Intel)
#   nebioncli-darwin-arm64   (macOS Apple Silicon)
#   nebioncli-windows-amd64  (Windows x86_64)
#
# From: https://your-nebion-instance/cli/download/{binary-name}
# Then rename to nebioncli and place in your PATH

Verify installation:

bash

nebioncli version

Getting Started

After logging in, run nebioncli hub to open an interactive dashboard where you can browse all projects and environments, view logs, and SSH into containers.

bash

nebioncli login

Your browser opens to the Nebion login page. After authenticating, return to the terminal. You stay logged in until you explicitly log out.

bash

# Login to a custom instance
nebioncli login --host https://custom.nebion.io

# Login without auto-opening browser
nebioncli login --no-browser

# Use a custom OAuth2 client ID
nebioncli login --client-id my-client

Commands

hub - Interactive Dashboard

bash

nebioncli hub

Opens a full-screen terminal dashboard for browsing projects and environments. The hub provides a two-panel layout: a project list on the left and environment details on the right, with built-in access to logs, deployment history, and diagnostics.

Navigation:

Key	Action
`Tab`	Switch between project list and environment list
`Enter`	Select item / open action menu
`/`	Filter current list
`Esc`	Go back / close panel
`?`	Show all keybindings
`q`	Quit

Environment actions (when an environment is selected):

Key	Action
`s`	SSH into environment
`l`	Open log viewer
`u`	Open environment URL in browser
`m`	View deployment history
`d`	View diagnostics (failed environments)
`o`	Switch organization
`r`	Refresh data

The log viewer supports follow mode (f), service filtering (s), text search (g), and line wrapping (w).

doctor - Validate Configuration

bash

nebioncli doctor                  # detect the recipe from .nebion.yml
nebioncli doctor --recipe manual  # validate as a manual-recipe project

Run from your project root to validate .nebion.yml — and, for the Docker recipe, your Docker Compose file — before deploying. The doctor applies the same rules as the deployment itself, so it catches problems that would otherwise surface as a failed deployment or a disabled action.

The recipe to validate comes from --recipe, then from an optional recipe: key in .nebion.yml, and is otherwise detected from the file: tasks.deploy / tasks.destroy mean manual, Docker keys or a compose file mean Docker, and a file with both sections is checked for both. Nebion itself uses the recipe set on the project or environment.

Checks performed:

Section	What it validates
Configuration	`.nebion.yml` exists, valid YAML and structure, no unknown fields (nested ones included), detected recipe
Docker Compose	Compose file exists, valid syntax, services defined (Docker recipe)
Routing	With `traefik.services`: every entry points at a compose service, valid `port`, `path_prefix` starts with `/`, valid `subdomain` / `domain`, exactly one entry serves the environment domain. Otherwise: `nginx_service` matches a compose service, valid `traefik_port`
Deployment Tasks	`pre-rollout` / `post-rollout` tasks have `command` and `service`, and the service exists in compose (Docker recipe)
Manual Tasks	`tasks.deploy` is present and non-empty, every task has a `command` (manual recipe)
Container Registries	Each registry, and the custom variables its credentials are read from (`REGISTRY_<KEY>_USERNAME` / `_PASSWORD`)
Actions	Every action has a `command`; its `service` (default `php`) exists in compose; `artifacts.paths` is non-empty, relative and free of `..`; `if-no-files` is `warn`, `error` or `ignore`; no `result: file`
Variables	Reserved `nebion_` prefix not used; compose `${VAR}` references resolve when a local `.nebion.env` exists

Outputs a color-coded report with pass, warning, error and hint lines. Exits with code 1 if any errors are found, 0 otherwise.

The doctor also suggests corrections for typos in field names — for example nginx-service suggests nginx_service, and comand inside an action suggests command.

ssh - Connect to a Container

bash

# Interactive selection (project > environment > container)
nebioncli ssh

# Direct connection
nebioncli ssh -p myproject -e 42 -c php

# Connect to manual environment
nebioncli ssh -p myproject -e staging -c nginx

Flag	Short	Description
`--project`	`-p`	Project name or ID
`--environment`	`-e`	PR number or environment name
`--container`	`-c`	Container name (e.g., `php`, `nginx`)

Press Esc at any prompt to cancel.

vars - Manage Environment Variables

bash

# Keys only, grouped into custom and system
nebioncli vars list -p myproject -e staging

# Set one or more variables (KEY=value)
nebioncli vars set -p myproject -e staging FEATURE_X=on DEBUG=0

# Remove variables
nebioncli vars unset -p myproject -e staging DEBUG

Lists, sets and removes the custom variables of an environment — the same ones as on its Variables tab. Values are write-only: list shows each key and whether it is custom or a read-only system variable (nebion_*), and no command ever prints a value.

Without -p/-e the CLI asks you to pick a project and an environment. Names must consist of letters, digits and underscores and may not start with a digit; names starting with nebion_ are reserved and rejected before any request is made.

Flag	Short	Description
`--project`	`-p`	Project name or ID
`--environment`	`-e`	PR number or environment name

Redeploy Required

A change is stored immediately but only reaches the containers with the next deployment. After set or unset the CLI reminds you to press Deploy on the environment page, and list shows the same hint while a redeploy is pending.

deploy - Deploy an Environment

bash

# Start a deployment and return immediately
nebioncli deploy -p myproject -e staging

# Start a deployment and wait for the result
nebioncli deploy -p myproject -e staging --wait

Starts the same deployment as the Deploy button on the environment page: the latest code of the environment's branch is pulled and the environment is redeployed. Protected environments can be deployed too, but never from scratch. While a deployment of the environment is already queued or running, the command fails with the same message the dashboard shows.

Without --wait the command prints the deployment task that was created and returns. With --wait it polls the environment every five seconds until the deployment finishes and exits with code 0 on success, 1 when the deployment failed (the failed step and its output are printed), or 2 when it is still running after 30 minutes (the deployment itself continues).

Flag	Short	Description
`--project`	`-p`	Project name or ID
`--environment`	`-e`	PR number or environment name
`--wait`		Wait for the deployment to finish and exit non-zero on failure

action - Run Environment Actions

The action CLI command is not yet available. Actions can currently be triggered from the UI.

bash

# List available actions for an environment
nebioncli action list

# Run an action (interactive project/environment selection)
nebioncli action run cache-clear

# Run with explicit project and environment
nebioncli action run db-dump --project mysite --env pr-42

# Download artifact from the last file-producing action run
nebioncli action download db-dump

# Download from a specific run
nebioncli action download --run-id abc123

Subcommand	Description
`list`	Show available actions for an environment
`run <action-id>`	Trigger an action
`download <action-id>`	Download the artifact from a file action

Flag	Short	Description
`--project`	`-p`	Project name or ID
`--environment`	`-e`	PR number or environment name
`--run-id`		Specific action run ID (for download)

Actions are defined in .nebion.yml. See Actions for configuration details.

logs - View Container Logs

bash

# Interactive selection
nebioncli logs

# Fetch last 500 lines
nebioncli logs -n 500

# Follow logs in real-time (Ctrl+C to stop)
nebioncli logs -f

# Direct access
nebioncli logs -p myproject -e 42 -c php -f

Flag	Short	Description
`--project`	`-p`	Project name or ID
`--environment`	`-e`	PR number or environment name
`--container`	`-c`	Container name
`--lines`	`-n`	Number of lines (default: 100)
`--follow`	`-f`	Stream new logs in real-time

url - Open Environment URL

bash

# Interactive selection, opens in browser
nebioncli url

# Open PR-42's URL
nebioncli url 42

# Output URL to stdout (for scripting)
nebioncli url --pipe
nebioncli url -p myproject -e 42 --pipe

The CLI auto-detects the project if you run it from inside a Git repository that matches a Nebion project.

org - Manage Organizations

bash

# List your organizations
nebioncli org list

# Show current organization
nebioncli org current

# Switch organization (interactive)
nebioncli org switch

# Switch by name or ID
nebioncli org switch "ACME Corp"
nebioncli org switch 5

All other commands (ssh, logs, url) operate within the active organization.

logout / update / version

bash

# Remove stored credentials
nebioncli logout

# Download and install the latest CLI version
nebioncli update

# Show version
nebioncli version

MCP Server

bash

nebioncli mcp

The mcp command starts a Model Context Protocol (MCP) server over stdio. It exposes Nebion operations as tools that an MCP client — such as Claude Code — can call directly, letting an AI assistant inspect your projects, environments, deployment status, failure diagnostics and variable keys from your editor or chat. With --allow-write it can also set and unset environment variables and start deployments.

You don't run nebioncli mcp yourself; your MCP client launches and talks to it. It reuses the credentials from nebioncli login and the active organization from nebioncli org switch, so it acts as the logged-in user with exactly their access to organizations and projects. No extra OAuth setup is needed in the client.

Read-only by default

Without --allow-write the MCP server exposes inspection tools only. Stopping or deleting environments is never possible through MCP; --allow-write adds the two variable tools and deploy_environment, and variable values are never returned.

Connect from Claude Code

Make sure nebioncli is logged in and on your PATH, then register the server:

bash

claude mcp add nebion -- nebioncli mcp

The -- separates Claude Code's own flags from the command it should run. After adding the server, Claude Code can call the Nebion tools in any session.

Choosing a scope: claude mcp add accepts a --scope flag that controls where the server is registered:

Scope	Flag	Stored in	Use for
Local	`--scope local` (default)	Your user settings, this project only	Personal use on a single project
Project	`--scope project`	`.mcp.json` (committed to the repo)	Sharing the server with your whole team via Git
User	`--scope user`	Your user settings, all projects	Personal use across every project

When you share the server at project scope, the .mcp.json file is committed to Git, so everyone on the team gets it. For it to work for all of them, nebioncli must resolve from each person's PATH — use the bare nebioncli command (as shown above), not an absolute path that only exists on your machine.

Allowing writes: the server is read-only by default. Add --allow-write to the command to also expose set_variables, unset_variables and deploy_environment:

bash

claude mcp add nebion -- nebioncli mcp --allow-write

Available tools

Eight tools are always available and read-only:

Tool	Parameters	Description
`whoami`	—	Current authenticated user and the organizations they belong to (id, name, role)
`list_projects`	—	Projects in the active organization
`list_environments`	`project_id`	Environments (PR and manual) for a project, with status, URL, branch, and PR metadata
`get_environment_status`	`environment_id`	Deployment task history and current status for an environment
`get_deploy_diagnostics`	`environment_id`	Diagnostics for the most recent failed deployment — the failed task and error details, plus the raw output as a fallback
`get_task_detail`	`environment_id`, `task_id`	Parsed steps for a specific deployment task
`get_task_log`	`environment_id`, `task_id`	Raw, unparsed Ansible log for a specific deployment task
`list_variables`	`environment_id`	Variable keys of an environment, each marked `custom` or `system`, plus `needs_redeploy`; values are never returned

With --allow-write three more tools change state. Variable changes take effect on the next deployment:

Tool	Parameters	Description
`set_variables`	`environment_id`, `variables` (`KEY: value` object)	Set custom variables; `nebion_*` keys are rejected
`unset_variables`	`environment_id`, `keys` (list)	Remove custom variables by key
`deploy_environment`	`environment_id`	Start a deployment (same as the Deploy button); returns the deployment task id at once — poll `get_environment_status` until `environment_status` leaves `running`

Building from source

Prebuilt binaries are available from the Install section, so most users never need a Go toolchain. If you do build nebioncli yourself, the MCP server requires Go 1.25 or newer.

Configuration

Storage Location & Files

The CLI stores configuration and credentials in your user config directory:

Platform	Directory
Linux	`~/.config/nebioncli/`
macOS	`~/.config/nebioncli/`
Windows	`%APPDATA%\nebioncli\`

If XDG_CONFIG_HOME is set, the CLI uses $XDG_CONFIG_HOME/nebioncli/ instead.

Files

File	Purpose
`config.json`	Instance URL, active organization
`credentials.json`	OAuth2 tokens (access + refresh)
`id_ed25519` / `id_ed25519.pub`	SSH keypair for container access

Files are created automatically on first login or ssh use. The private key never leaves your machine - the CLI sends your public key to Nebion and receives a short-lived certificate.

Warning: credentials.json contains sensitive tokens. It is created with 0600 permissions (owner read/write only). Do not share this file or commit it to version control.

Directory Permissions

bash

chmod 700 ~/.config/nebioncli
chmod 600 ~/.config/nebioncli/credentials.json
chmod 600 ~/.config/nebioncli/config.json
chmod 600 ~/.config/nebioncli/id_ed25519
chmod 644 ~/.config/nebioncli/id_ed25519.pub

Resetting Configuration

To completely reset the CLI:

bash

rm -rf ~/.config/nebioncli
nebioncli login

This removes credentials, configuration, and SSH keys. New keys are generated on next use.

Multiple Instances

The CLI supports one Nebion instance at a time. To switch:

bash

nebioncli login --host https://other.nebion.io

This replaces existing credentials.

Uninstall

Linux / macOS:

bash

rm $(which nebioncli)
rm -rf ~/.config/nebioncli

Windows: Delete the nebioncli.exe binary and the %APPDATA%\nebioncli directory.

CLI Tool ​

Install ​

Login ​

Commands ​

hub - Interactive Dashboard ​

doctor - Validate Configuration ​

ssh - Connect to a Container ​

vars - Manage Environment Variables ​

deploy - Deploy an Environment ​

action - Run Environment Actions ​

MCP Server ​

Connect from Claude Code ​

Available tools ​

Configuration ​

Files ​

Directory Permissions ​

Resetting Configuration ​

Multiple Instances ​

CLI Tool

Install

Login

Commands

hub - Interactive Dashboard

doctor - Validate Configuration

ssh - Connect to a Container

vars - Manage Environment Variables

deploy - Deploy an Environment

action - Run Environment Actions

MCP Server

Connect from Claude Code

Available tools

Configuration

Files

Directory Permissions

Resetting Configuration

Multiple Instances