CLI

Manage environments from your terminal - create, start, stop, SSH into environments, and run automations.

Installation

Homebrew (macOS and Linux)

brew install gitpod-io/tap/ona

The formula auto-detects your OS and architecture. Updates are handled by brew upgrade ona.

macOS and Linux

curl -o ona -fsSL "https://app.gitpod.io/releases/cli/stable/gitpod-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed 's/x86_64/amd64/;s/\(arm64\|aarch64\)/arm64/')" && \
chmod +x ona && \
sudo mv ona /usr/local/bin

Direct download

Platform	Downloads
macOS	x86_64 \| arm64
Linux	x86_64 \| arm64
Windows	x86_64 \| arm64

After downloading, make the binary executable and move it to your PATH:

chmod +x ona
sudo mv ona /usr/local/bin

macOS security warning

If macOS shows a security warning, approve the app in System Settings → Privacy & Security, or run:

xattr -d com.apple.quarantine ona

Verify download integrity

Verified installationUse SLSA verification during initial installation:

curl -fsSL https://app.gitpod.io/releases/cli/install.sh | VERIFY_SLSA=true bash

Requirements: jq, openssl, curl

If SLSA verification fails, the installation aborts with an error. There is no fallback to unverified download - this ensures you’re always notified of potential tampering.

Manual SLSA verificationSLSA verification cryptographically proves the CLI was built by the official build system.The verification script checks:

Artifact SHA256 matches the attestation subject digest
Provenance metadata confirms the build came from gitpod-io/gitpod-next
Certificate was issued by Sigstore
Entry exists in the Rekor transparency log
DSSE envelope structure is valid

Requirements: jq, openssl, curl

# Get manifest and extract packageHash for your platform
PLATFORM="linux-amd64"  # or darwin-amd64, darwin-arm64, windows-amd64
MANIFEST=$(curl -sL https://app.gitpod.io/releases/cli/stable/manifest.json)
VERSION=$(echo "$MANIFEST" | jq -r '.version')
HASH=$(echo "$MANIFEST" | jq -r ".downloads[\"$PLATFORM\"].packageHash")

# Download tarball and attestation
BASE_URL="https://app.gitpod.io/releases/cli/releases/$VERSION"
curl -fsSL -O "$BASE_URL/$HASH.tar.gz"
curl -fsSL -O "$BASE_URL/$HASH.tar.gz.att"

# Download and run verification script
curl -fsSL -O https://app.gitpod.io/releases/cli/verify-slsa.sh
chmod +x verify-slsa.sh
./verify-slsa.sh "$HASH.tar.gz"

# Extract and install
tar -xzf "$HASH.tar.gz" ./ona-cli
chmod +x ona-cli
sudo mv ona-cli /usr/local/bin/ona

Option 2: Checksum VerificationGet the expected checksum:

curl -sL https://app.gitpod.io/releases/cli/stable/manifest.json | jq -r '.downloads["<platform>"].digest'

Calculate your file’s checksum and compare:

shasum -a 256 ona

Authentication

ona login

Opens your browser to authenticate and stores credentials locally.

Personal access token

For CI/CD pipelines and scripts, use a personal access token:

ona login --token "your-token-here"

Or set the environment variable:

export ONA_TOKEN="your-token-here"
ona login

Inside Ona environments

The CLI is pre-installed and automatically authenticated with limited access. Run ona login to upgrade to full access. When running inside an environment, the CLI automatically detects the current environment context. This means:

Environment ID is inferred: Commands like ona automations, ona environment port, and other environment-specific commands work without requiring --environment-id
Context preserved after login: When you run ona login inside an environment, the environment ID is preserved in your CLI context (as long as the login host matches the environment’s host). This allows you to continue using environment-specific commands after authentication.

# Inside an environment - no --environment-id needed
ona automations service list
ona environment port open 3000

# After running ona login, these still work without --environment-id
ona login
ona automations task start my-task

If you log into a different host than your environment (e.g., logging into app.gitpod.io from an environment on ona.e-corp.com), the environment ID will not be preserved.

ona environment port open defaults to creator-only access. On a runner that cannot enforce private access, an implicit open falls back to public access with a warning. Pass --admission creator_only to fail closed, or --admission everyone when an unauthenticated URL is required.

Common commands

Command	Description
`ona whoami`	Show current user and access level
`ona environment list`	List your environments
`ona environment list --search <term>`	Search environments by ID, name, repository URL, or branch
`ona environment create <repo-url>`	Create a new environment
`ona environment create <repo-url> --inactivity-timeout 1h`	Create an environment with a custom auto-stop timeout
`ona environment update <id-or-name> --name "<name>"`	Rename an environment
`ona environment update <id-or-name> --inactivity-timeout 3h`	Update an environment’s auto-stop timeout
`ona environment start <id-or-name>`	Start an environment
`ona environment stop <id-or-name>`	Stop an environment
`ona environment delete <id-or-name>`	Delete an environment
`ona environment ssh <id-or-name>`	SSH into an environment
`ona environment logs <id-or-name>`	View environment logs
`ona environment keep-alive`	Keep environment alive while a process runs

Use -o json or -o yaml for machine-readable output.

Using partial environment IDs

Instead of typing full UUIDs, you can use any substring of an environment ID:

# Full UUID
ona environment ssh 019194a6-f0b0-70a1-beae-99718c351b04

# Prefix
ona environment ssh 019194a6

# Suffix
ona environment ssh 351b04

# Any substring
ona environment ssh 70a1-beae

The CLI resolves the partial ID if it uniquely identifies an environment. If the substring matches multiple environments, you’ll see an error listing all matching IDs. If no environments match, you’ll be prompted to run ona environment list to see available environments.

Using environment names

Give an environment a memorable name when you do not want to copy its UUID:

# Rename an environment
ona environment update 019194a6 --name "api-dev"

# Use the name after renaming
ona environment ssh api-dev
ona environment port list api-dev
ona automations task start build --environment-id api-dev

Most user-facing environment commands accept an environment ID, a unique partial ID, or an exact environment name. Name matching is case-insensitive. To clear a custom name, pass an empty value:

ona environment update api-dev --name ""

Use --inactivity-timeout on create or update to set a custom auto-stop timeout. See auto-stop timeout for details. Names are not required to be unique. If a name matches more than one environment, the CLI asks you to use an environment ID instead. Search across environment IDs, names, repository URLs, and branches with:

ona environment list --search api-dev

SSH access

Configure SSH for direct access:

ona environment ssh-config

Then connect using:

ssh <environment-id>.ona.environment

Generated SSH aliases and stored CLI contexts use environment IDs, not names. This keeps them stable if an environment is renamed. You can also use partial environment IDs or environment names with the ona environment ssh command:

# Connect using a prefix instead of the full UUID
ona environment ssh 019194a6

# Or use any unique substring
ona environment ssh beae-997

# Or use an exact environment name
ona environment ssh api-dev

For file transfers, use the -O flag:

scp -O <environment-id>.ona.environment:/workspaces/project/file.txt ./local-file.txt

Port management

ona environment port list
ona environment port list api-dev
ona environment port open <port> --name "my-service"
ona environment port close <port>

Automation commands

ona automations init
ona automations update automations.yaml
ona automations task list
ona automations task start <task-reference>
ona automations task logs <task-reference>
ona automations service list
ona automations service start <service-reference>

Use --environment-id <id-or-name> to target a specific environment from outside that environment.

Prebuild and warm pool commands

# List prebuilds for a project
ona prebuild list --project-id <project-id>

# Trigger a prebuild
ona prebuild trigger <project-id>

# List all warm pools in the organization
ona prebuild warm-pool list

# List warm pools for a specific project
ona prebuild warm-pool list --project-id <project-id>

# Create a warm pool (project admin required)
ona prebuild warm-pool create <project-id> --environment-class-id <class-id> --min-size 1 --max-size 2

# Get warm pool details
ona prebuild warm-pool get <warm-pool-id>

# Update pool scaling bounds
ona prebuild warm-pool update <warm-pool-id> --min-size 1 --max-size 3

# Delete a warm pool
ona prebuild warm-pool delete <warm-pool-id>

See Warm Pools for configuration and auditing details.

Webhook commands

ona webhook create --name "My Webhook" --type repository --scope "owner/repo" --provider github
ona webhook secret get <webhook-id>

See Webhooks for setup details and SCM registration.

Dotfiles management

Manage your dotfiles configuration directly from the CLI:

# View current dotfiles configuration
ona user dotfiles get

# Set dotfiles repository
ona user dotfiles set --repository https://github.com/user/dotfiles

# Clear dotfiles configuration
ona user dotfiles set

The get command supports output formats:

ona user dotfiles get -o json
ona user dotfiles get -o yaml

See dotfiles documentation for more information about using dotfiles with Ona.

Project and group management

ona project list
ona project create <repo-url>
ona group list
ona group create --name "Team Name"

Configuration

The CLI stores configuration at ~/.ona/configuration.yaml.

ona config context list
ona config context use <context-name>
ona config set --autoupdate=true
ona config set --verify-slsa=true
ona config set --release-channel=latest
ona config set --organization-id=<org-id>

Shell completion

# Bash
ona completion bash > /etc/bash_completion.d/ona

# Zsh
ona completion zsh > "${fpath[1]}/_ona"

# Fish
ona completion fish > ~/.config/fish/completions/ona.fish

Updates

ona version
ona version update

SLSA verification for updates

Enable cryptographic verification of CLI updates to ensure binary integrity: Per-update verification:

ona version update --verify-slsa

Persistent config:

ona config set --verify-slsa=true
ona version update  # Now uses verification by default

The --verify-slsa flag takes precedence over the config value when explicitly set.

If SLSA verification fails, the update aborts with an error. There is no fallback to unverified download - this ensures you’re always notified of potential tampering.

Run ona help or add --help to any command for more information.

Troubleshooting

Authentication issues

ona login --non-interactive  # For headless environments
ona login --token "<token>"  # Use token directly

SSH connection failures

If you see too many authentication failures, add to ~/.ssh/ona/config:

Host *.ona.environment
    IdentitiesOnly yes

Debug with:

ssh -vvv <environment-id>.ona.environment

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

Installation

Homebrew (macOS and Linux)

macOS and Linux

Direct download

Authentication

Personal access token

Inside Ona environments

Common commands

Using partial environment IDs

Using environment names

SSH access

Port management

Automation commands

Prebuild and warm pool commands

Webhook commands

Dotfiles management

Project and group management

Configuration

Shell completion

Updates

SLSA verification for updates

Troubleshooting

​Installation

​Homebrew (macOS and Linux)

​macOS and Linux

​Direct download

​Authentication

​Browser login

​Personal access token

​Inside Ona environments

​Common commands

​Using partial environment IDs

​Using environment names

​SSH access

​Port management

​Automation commands

​Prebuild and warm pool commands

​Webhook commands

​Dotfiles management

​Project and group management

​Configuration

​Shell completion

​Updates

​SLSA verification for updates

​Troubleshooting

Installation

Homebrew (macOS and Linux)

macOS and Linux

Direct download

Authentication

Browser login

Personal access token

Inside Ona environments

Common commands

Using partial environment IDs

Using environment names

SSH access

Port management

Automation commands

Prebuild and warm pool commands

Webhook commands

Dotfiles management

Project and group management

Configuration

Shell completion

Updates

SLSA verification for updates

Troubleshooting