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.
For installation and setup, see 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 update <id-or-name> --name "<name>" | Rename an environment |
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 inside an environment |
ona environment keep-alive | Keep environment alive while a process runs |
Partial environment IDs
Instead of typing full UUIDs, use any substring of an environment ID:
# Full UUID
ona environment ssh 019194a6-f0b0-70a1-beae-99718c351b04
# Prefix
ona environment ssh 019194a6
# Any substring
ona environment ssh 70a1-beae
Environment names
Use ona environment update to set or clear a custom name:
ona environment update 019194a6 --name "api-dev"
ona environment update api-dev --name ""
ona environment ssh api-dev
ona environment port list api-dev
ona automations task start build --environment-id api-dev
ona environment list --search api-dev
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) |
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 |
--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 |
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 |
-o json and -o yaml output. See dotfiles documentation.
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 |
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.
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) |
--runner-host when the API is unreachable and you need to test runner connectivity directly.
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
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 |
~/.ona/configuration.yaml.
