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: 
ona project list
Use -o json for machine-readable output: 
ona project list -o json

​
Discover environment classes

Environment classes define the compute resources (CPU, memory) for your environment. List available classes: 
ona environment list-classes
Filter by runner: 
ona 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: 
ona environment create <project-id>

​
From a context URL

Create directly from a repository URL. Requires an environment class: 
ona 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=$(ona environment create <project-id> --dont-wait)
Then poll for readiness: 
ona environment get "$ENV_ID" -o json

​
List environments

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

​
Run commands

Execute commands inside a running environment using exec: 
ona 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
ona environment exec <environment-id> -- make build

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

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

# Get structured output for parsing
ona 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: 
ona environment ssh <environment-id>
Run a single command over SSH: 
ona environment ssh <environment-id> -- ls -la
See the CLI reference for SSH setup details.

​
Clean up

Stop an environment to preserve its state: 
ona environment stop <environment-id>
Delete an environment permanently: 
ona 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=$(ona environment create <project-id> --dont-wait)
echo "Created environment: $ENV_ID"

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

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

# Clean up
ona 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=$(ona environment create <project-id> --dont-wait)

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

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