Skip to main content
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

CommandDescription
ona environment listList your environments
ona environment create <repo-url>Create a new environment
ona environment start <id>Start an environment
ona environment stop <id>Stop an environment
ona environment delete <id>Delete an environment
ona environment ssh <id>SSH into an environment
ona environment ssh-configConfigure SSH for direct access
ona environment logs <id>View environment logs
ona environment exec <id> -- <cmd>Run a command inside an environment
ona environment keep-aliveKeep 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
The CLI resolves the partial ID if it uniquely identifies an environment.

​
Port commands

CommandDescription
ona environment port listList open ports
ona environment port open <port>Open a port (supports --name)
ona environment port close <port>Close a port

​
Automation commands

CommandDescription
ona automations initInitialize automations config
ona automations update automations.yamlUpdate automations from file
ona automations task listList tasks
ona automations task start <ref>Start a task
ona automations task logs <ref>View task logs
ona automations service listList services
ona automations service start <ref>Start a service

​
Webhook commands

CommandDescription
ona webhook createCreate a webhook (--name, --type, --scope, --provider)
ona webhook secret get <id>Get the signing secret for a webhook
See Webhooks for setup and SCM registration.

​
Dotfiles commands

CommandDescription
ona user dotfiles getView current dotfiles config
ona user dotfiles set --repository <url>Set dotfiles repository
ona user dotfiles setClear dotfiles config
Supports -o json and -o yaml output. See dotfiles documentation.

​
Project and group commands

CommandDescription
ona project listList projects
ona project create <repo-url>Create a project
ona group listList groups
ona group create --name "<name>"Create a group

​
Identity commands

CommandDescription
ona whoamiShow current user and access level
ona loginAuthenticate via browser
ona login --token "<token>"Authenticate with PAT

​
Configuration commands

CommandDescription
ona config context listList 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. 
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.
FlagDefaultDescription
--iterations10Number of repeated requests
--timeout30sTimeout per request
--interval1sInterval between requests
--show-headersfalseShow 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
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

CommandDescription
ona versionShow CLI version
ona version updateUpdate to latest version
ona version update --verify-slsaUpdate with SLSA verification
ona config set --verify-slsa=trueEnable SLSA verification for all future updates
ona config set --autoupdate=trueEnable 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.