> ## 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 command reference

> Common Ona CLI commands for environments, automations, and configuration.

For installation and setup, see [CLI](/ona/integrations/cli).

Use `-o json` or `-o yaml` with any command for machine-readable output. Run `ona help` or add `--help` to any command for details.

## Environment commands

| Command                                                       | Description                                                                                                                                     |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `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 ssh-config`                                  | Configure SSH for direct access                                                                                                                 |
| `ona environment logs <id-or-name>`                           | View environment logs                                                                                                                           |
| `ona environment exec <id-or-name> -- <cmd>`                  | [Run a command](/ona/environments/agent-environments#run-commands) inside an environment                                                        |
| `ona environment keep-alive`                                  | [Keep environment alive](/ona/organizations/policies/environment-timeout#keep-environment-alive-during-long-running-tasks) while a process runs |

### Partial environment IDs

Instead of typing full UUIDs, 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

# Any substring
ona environment ssh 70a1-beae
```

The CLI resolves the partial ID if it uniquely identifies an environment.

### Environment names

Use `ona environment update` to set or clear a custom name:

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

Use `--inactivity-timeout` on `create` or `update` to set a custom auto-stop timeout. See [environment timeout](/ona/organizations/policies/environment-timeout) for details.

Most user-facing environment commands accept a full environment ID, unique partial ID, or exact environment name:

```bash theme={null}
ona environment ssh api-dev
ona environment port list api-dev
ona automations task start build --environment-id api-dev
```

Environment name matching is case-insensitive. Environment names are not unique; if a name matches more than one environment, use an environment ID.

Search across environment IDs, names, repository URLs, and branches:

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

Generated SSH aliases and stored CLI contexts remain ID-based. Use `ssh <environment-id>.ona.environment` for direct SSH, or `ona environment ssh <name>` when you want the CLI to resolve a name.

## Port commands

| Command                                  | Description                                                      |
| ---------------------------------------- | ---------------------------------------------------------------- |
| `ona environment port list [id-or-name]` | List open ports                                                  |
| `ona environment port open <port>`       | Open a port (supports `--name`, `--protocol`, and `--admission`) |
| `ona environment port close <port>`      | Close a port                                                     |

## Dev container commands

| Command                                                                 | Description                                          |
| ----------------------------------------------------------------------- | ---------------------------------------------------- |
| `ona environment devcontainer rebuild`                                  | Rebuild the dev container                            |
| `ona environment devcontainer validate .devcontainer/devcontainer.json` | Validate a devcontainer.json file against the schema |
| `ona environment devcontainer logs [id-or-name]`                        | View dev container build logs (supports `--follow`)  |

The environment must be running to rebuild.

## Automation commands

| Command                                   | Description                   |
| ----------------------------------------- | ----------------------------- |
| `ona automations init`                    | Initialize automations config |
| `ona automations update automations.yaml` | Update automations from file  |
| `ona automations task list`               | List tasks                    |
| `ona automations task start <ref>`        | Start a task                  |
| `ona automations task logs <ref>`         | View task logs                |
| `ona automations service list`            | List services                 |
| `ona automations service start <ref>`     | Start a service               |

Use `--environment-id <id-or-name>` to target a specific environment for automation commands.

## Webhook commands

| Command                       | Description                                                    |
| ----------------------------- | -------------------------------------------------------------- |
| `ona webhook create`          | Create a webhook (`--name`, `--type`, `--scope`, `--provider`) |
| `ona webhook secret get <id>` | Get the signing secret for a webhook                           |

See [Webhooks](/ona/automations/webhooks) for setup and SCM registration.

## Dotfiles commands

| Command                                    | Description                  |
| ------------------------------------------ | ---------------------------- |
| `ona user dotfiles get`                    | View current dotfiles config |
| `ona user dotfiles set --repository <url>` | Set dotfiles repository      |
| `ona user dotfiles set`                    | Clear dotfiles config        |

Supports `-o json` and `-o yaml` output. See [dotfiles documentation](/ona/configuration/dotfiles/overview).

## Project and group commands

| Command                            | Description      |
| ---------------------------------- | ---------------- |
| `ona project list`                 | List projects    |
| `ona project create <repo-url>`    | Create a project |
| `ona group list`                   | List groups      |
| `ona group create --name "<name>"` | Create a group   |

## Organization security policy commands

| Command                                                             | Description                                          |
| ------------------------------------------------------------------- | ---------------------------------------------------- |
| `ona organization security-policy list`                             | List security policies in the active organization    |
| `ona organization security-policy init policy.yaml`                 | Create and validate a security policy YAML file      |
| `ona organization security-policy init policy.yaml --validate-only` | Validate a security policy YAML file                 |
| `ona organization security-policy create policy.yaml`               | Create a security policy from a YAML or JSON file    |
| `ona organization security-policy get <id> -o yaml`                 | Export a security policy                             |
| `ona organization security-policy update <id> policy.yaml`          | Update a security policy from a YAML or JSON file    |
| `ona organization security-policy update policy.yaml`               | Update a security policy using the ID in the file    |
| `ona organization security-policy delete <id>`                      | Delete a security policy                             |
| `ona organization security-policy set-default <id>`                 | Use a security policy for newly created environments |
| `ona organization security-policy set-default --clear`              | Clear the default security policy                    |

`create` and `update` accept the YAML emitted by `get -o yaml`, so exported policies can be edited and applied again:

```bash theme={null}
ona organization security-policy get <id> -o yaml > policy.yaml
ona organization security-policy update policy.yaml
```

Pass `--organization-id <id>` to `list`, `create`, or `set-default` to target an organization other than the active CLI context.

## Identity commands

| Command                       | Description                        |
| ----------------------------- | ---------------------------------- |
| `ona whoami`                  | Show current user and access level |
| `ona login`                   | Authenticate via browser           |
| `ona login --token "<token>"` | Authenticate with PAT              |

## Configuration commands

| Command                         | Description       |
| ------------------------------- | ----------------- |
| `ona config context list`       | List CLI contexts |
| `ona config context use <name>` | Switch context    |

## Network troubleshooting

Run connectivity checks from your machine against Ona services. Useful for diagnosing DNS, TLS, proxy, or intermittent connection issues.

```bash theme={null}
ona network-troubleshoot
```

The command tests DNS resolution, TCP connections, TLS handshakes, and authenticated API requests. It also checks runner connectivity by discovering runner hosts via the API.

| Flag             | Default | Description                                          |
| ---------------- | ------- | ---------------------------------------------------- |
| `--iterations`   | `10`    | Number of repeated requests                          |
| `--timeout`      | `30s`   | Timeout per request                                  |
| `--interval`     | `1s`    | Interval between requests                            |
| `--show-headers` | `false` | Show request/response headers and body               |
| `--runner-host`  | -       | Runner hostname(s) to check (bypasses API discovery) |

Use `--runner-host` when the API is unreachable and you need to test runner connectivity directly.

## 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
```

## Version and updates

| Command                             | Description                                     |
| ----------------------------------- | ----------------------------------------------- |
| `ona version`                       | Show CLI version                                |
| `ona version update`                | Update to latest version                        |
| `ona version update --verify-slsa`  | Update with SLSA verification                   |
| `ona config set --verify-slsa=true` | Enable SLSA verification for all future updates |
| `ona config set --autoupdate=true`  | Enable automatic updates                        |

SLSA verification cryptographically proves the CLI binary was built by the official build system. When enabled, every update checks the Sigstore certificate, Rekor transparency log, and provenance metadata. If verification fails, the update aborts.

Configuration is stored at `~/.ona/configuration.yaml`.

## Related

* [CLI installation and setup](/ona/integrations/cli) - install, authenticate, and connect
* [automations.yaml schema](/ona/reference/automations-yaml-schema) - task and service configuration
* [Environment variables](/ona/reference/environment-variables) - variable behavior and availability