Skip to main content
Use the Ona CLI to create, manage, and run commands in environments from external AI agents such as Claude Code, Cursor, or custom scripts. This guide covers the full lifecycle: discover resources, create an environment, execute commands, and clean up.

​
Prerequisites

​
Discover projects

List projects to find one to create an environment from: 
gitpod project list
Use -o json for machine-readable output: 
gitpod project list -o json

​
Discover environment classes

Environment classes define the compute resources (CPU, memory) for your environment. List available classes: 
gitpod environment list-classes
Filter by runner: 
gitpod environment list-classes --runner <runner-id>

​
Create an environment

​
From a project

The simplest way. The project already has a repository URL, environment class, and configuration: 
gitpod environment create <project-id>

​
From a context URL

Create directly from a repository URL. Requires an environment class: 
gitpod environment create <repo-url> --class <class-id>

​
Non-blocking creation

Use --dont-wait to return the environment ID immediately without waiting for it to start: 
ENV_ID=$(gitpod environment create <project-id> --dont-wait)
Then poll for readiness: 
gitpod environment get "$ENV_ID" -o json

​
List environments

gitpod environment list
Filter to JSON for parsing: 
gitpod environment list -o json

​
Run commands

Execute commands inside a running environment using exec: 
gitpod environment exec <environment-id> -- <command>
The command runs inside the environment’s dev container via the EnvironmentOps API (not SSH). The CLI waits for the command to complete and prints stdout/stderr.

​
Examples

# Run a build
gitpod environment exec <environment-id> -- make build

# Run tests with a longer timeout
gitpod environment exec <environment-id> --timeout 300 -- npm test

# Run in a specific directory
gitpod environment exec <environment-id> --working-dir /workspace/myproject -- cargo test

# Get structured output for parsing
gitpod environment exec <environment-id> -o json -- echo hello

​
Exit codes

The CLI exits with the same exit code as the remote command. A non-zero exit code means the command failed.

​
Flags

FlagDefaultDescription
--timeout120Command timeout in seconds
--working-dirworkspace folderWorking directory inside the environment
-o jsontableOutput format (json, yaml, table)

​
SSH access

For interactive sessions or when you need a persistent shell: 
gitpod environment ssh <environment-id>
Run a single command over SSH: 
gitpod environment ssh <environment-id> -- ls -la
See the CLI reference for SSH setup details.

​
Clean up

Stop an environment to preserve its state: 
gitpod environment stop <environment-id>
Delete an environment permanently: 
gitpod environment delete <environment-id>

​
Full workflow example

End-to-end script that creates an environment, runs a command, and cleans up: 
#!/bin/bash
set -euo pipefail

# Create environment from a project, wait for it to start
ENV_ID=$(gitpod environment create <project-id> --dont-wait)
echo "Created environment: $ENV_ID"

# Wait for the environment to be running
gitpod environment start "$ENV_ID"

# Run commands
gitpod environment exec "$ENV_ID" -- npm install
gitpod environment exec "$ENV_ID" --timeout 300 -- npm test

# Clean up
gitpod environment delete "$ENV_ID"
echo "Done"

​
JSON workflow for agents

Agents that parse structured output can use -o json throughout: 
# Create and capture the environment ID (--dont-wait prints the ID directly)
ENV_ID=$(gitpod environment create <project-id> --dont-wait)

# Check status
STATUS=$(gitpod environment get "$ENV_ID" -o json | jq -r '.[0].status.phase')

# Run a command and parse the result
RESULT=$(gitpod environment exec "$ENV_ID" -o json -- echo hello)
EXIT_CODE=$(echo "$RESULT" | jq -r '.[0].exit_code')
STDOUT=$(echo "$RESULT" | jq -r '.[0].stdout')