> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Manage environments, SSH access, and automations from your terminal.

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

## Installation

### Homebrew (macOS and Linux)

```bash theme={null}
brew install gitpod-io/tap/ona
```

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

### macOS and Linux

```bash theme={null}
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](https://app.gitpod.io/releases/cli/stable/gitpod-darwin-amd64) \| [arm64](https://app.gitpod.io/releases/cli/stable/gitpod-darwin-arm64) |
| Linux | [x86\_64](https://app.gitpod.io/releases/cli/stable/gitpod-linux-amd64) \| [arm64](https://app.gitpod.io/releases/cli/stable/gitpod-linux-arm64) |
| Windows | [x86\_64](https://app.gitpod.io/releases/cli/stable/gitpod-windows-amd64.exe) \| [arm64](https://app.gitpod.io/releases/cli/stable/gitpod-windows-arm64.exe) |

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

```bash theme={null}
chmod +x ona
sudo mv ona /usr/local/bin
```

> [accordion] macOS security warning
>
> If macOS shows a security warning, approve the app in **System Settings → Privacy & Security**, or run:
>
> ```bash theme={null}
> xattr -d com.apple.quarantine ona
> ```

> [accordion] Verify download integrity
>
> **Verified installation**
>
> Use SLSA verification during initial installation:
>
> ```bash theme={null}
> curl -fsSL https://app.gitpod.io/releases/cli/install.sh | VERIFY_SLSA=true bash
> ```
>
> Requirements: `curl`, `jq`, `awk`, `base64`, and either `sha256sum` or `shasum`. Legacy releases also require `tar`.
>
> > [!NOTE]
> >
> > If SLSA verification fails, the installation aborts with an error. There is no fallback to an unverified download.
>
> **[SLSA](https://slsa.dev) verification behavior**
>
> Use the verified installer above for both supported release layouts. It verifies legacy `packageHash` attestations and schema-v1 per-platform provenance with a pinned, checksummed Cosign binary before installing the CLI.
>
> **Checksum verification**
>
> Get the expected checksum:
>
> ```bash theme={null}
> curl -sL https://app.gitpod.io/releases/cli/stable/manifest.json | jq -r '.downloads["<platform>"].digest'
> ```
>
> Calculate your file's checksum and compare:
>
> ```bash theme={null}
> shasum -a 256 ona
> ```

## Authentication

### Browser login

```bash theme={null}
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](https://ona.com/docs/ona/integrations/personal-access-token.md):

```bash theme={null}
ona login --token "your-token-here"
```

Or set the environment variable:

```bash theme={null}
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 environment task`, `ona environment service`, `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.

```bash theme={null}
# Inside an environment - no --environment-id needed
ona environment service list
ona environment port open 3000

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

> [!NOTE]
>
> 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](https://ona.com/docs/ona/organizations/policies/environment-timeout.md#keep-environment-alive-during-long-running-tasks) 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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 environment 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:

```bash theme={null}
ona environment update api-dev --name ""
```

Use `--inactivity-timeout` on `create` or `update` to set a custom auto-stop timeout. See [auto-stop timeout](https://ona.com/docs/ona/organizations/policies/environment-timeout.md) 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:

```bash theme={null}
ona environment list --search api-dev
```

## SSH access

Configure SSH for direct access:

```bash theme={null}
ona environment ssh-config
```

Then connect using:

```bash theme={null}
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.

On macOS, configure SSH and add an environment to Codex with one command:

```bash theme={null}
ona env codex <environment-id-or-name>
```

The command refreshes the standard Ona SSH configuration and adds the environment's workspace directory to Codex as a remote project. It writes `$CODEX_HOME/codex-app/config.json` (usually `~/.codex/codex-app/config.json`), a Codex Desktop remote-setup payload containing the selected environment, then asks the app to apply it and connect through a Codex-specific SSH alias. The payload replaces any previous payload, but applying it preserves other remote connections and projects already stored by Codex Desktop.

The command does not change your normal Codex settings in `$CODEX_HOME/config.toml` (usually `~/.codex/config.toml`) or `environments.toml`.

The environment must be running with its workspace directory available. The generated Codex alias does not start stopped environments; start the environment before reconnecting if it has stopped. The `codex` command must be installed and authenticated in the environment.

You can also use partial environment IDs or environment names with the `ona environment ssh` command:

```bash theme={null}
# 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:

```bash theme={null}
scp -O <environment-id>.ona.environment:/workspaces/project/file.txt ./local-file.txt
```

## Port management

```bash theme={null}
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

```bash theme={null}
ona environment config init
ona environment config apply .ona/config.yaml
ona environment task list
ona environment task start <task-reference>
ona environment task logs <task-reference>
ona environment service list
ona environment service start <service-reference>
```

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

## Prebuild and warm pool commands

```bash theme={null}
# 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](https://ona.com/docs/ona/projects/warm-pools.md) for configuration and auditing details.

## Webhook commands

```bash theme={null}
ona webhook create --name "My Webhook" --type repository --scope "owner/repo" --provider github
ona webhook secret get <webhook-id>
```

See [Webhooks](https://ona.com/docs/ona/automations/webhooks.md) for setup details and SCM registration.

## Dotfiles management

Manage your dotfiles configuration directly from the CLI:

```bash theme={null}
# 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:

```bash theme={null}
ona user dotfiles get -o json
ona user dotfiles get -o yaml
```

See [dotfiles documentation](https://ona.com/docs/ona/configuration/dotfiles/overview.md) for more information about using dotfiles with Ona.

## Project and group management

```bash theme={null}
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`.

```bash theme={null}
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 theme={null}
# 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

```bash theme={null}
ona version
ona version update
```

### SLSA verification for updates

Enable cryptographic verification of CLI updates to ensure binary integrity:

**Per-update verification:**

```bash theme={null}
ona version update --verify-slsa
```

**Persistent config:**

```bash theme={null}
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.

> [!NOTE]
>
> 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

> [accordion] Authentication issues
>
> ```bash theme={null}
> ona login --non-interactive  # For headless environments
> ona login --token "<token>"  # Use token directly
> ```

> [accordion] SSH connection failures
>
> If you see `too many authentication failures`, add to `~/.ssh/ona/config`:
>
> ```
> Host *.ona.environment
>     IdentitiesOnly yes
> ```
>
> Debug with:
>
> ```bash theme={null}
> ssh -vvv <environment-id>.ona.environment
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.