CLI command reference

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 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 archive <id-or-name>`	Archive an environment, stopping it first if necessary
`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

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:

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 auto-stop timeout for details. Most user-facing environment commands accept a full environment ID, unique partial ID, or exact environment name:

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:

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 creator-only port by default; 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 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.

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

The public Veto Exec policy uses only spec.executables:

metadata:
  name: Veto Exec audit-first
spec:
  executables:
    defaultEffect: EFFECT_ALLOW
    rules:
      - path: npx
        effect: EFFECT_AUDIT
      - path: /usr/bin/curl
        effect: EFFECT_BLOCK

For executable policies:

Omit defaultEffect or set it to EFFECT_ALLOW.
Set each rule effect to EFFECT_AUDIT or EFFECT_BLOCK.
Use an absolute path or a bare executable name for each rule path.
Surrounding whitespace is ignored. Do not use a whitespace-only selector, ., .., or a relative path with a directory separator.

Validate the file before creating or updating the policy:

ona organization security-policy init veto-exec-policy.yaml --validate-only

Creating a policy stores an inactive definition. Assignment validates materializability before the policy can apply to new environments; updating an already-assigned policy validates its new spec again. create and update accept the YAML emitted by get -o yaml, so exported policies can be edited and applied again:

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.

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
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.

CLI installation and setup - install, authenticate, and connect
automations.yaml schema - task and service configuration
Environment variables - variable behavior and availability

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

CLI command reference

Environment commands

Partial environment IDs

Environment names

Port commands

Dev container commands

Automation commands

Webhook commands

Dotfiles commands

Project and group commands

Organization security policy commands

Identity commands

Configuration commands

Network troubleshooting

Shell completion

Version and updates

​Environment commands

​Partial environment IDs

​Environment names

​Port commands

​Dev container commands

​Automation commands

​Webhook commands

​Dotfiles commands

​Project and group commands

​Organization security policy commands

​Identity commands

​Configuration commands

​Network troubleshooting

​Shell completion

​Version and updates

​Related

Environment commands

Partial environment IDs

Environment names

Port commands

Dev container commands

Automation commands

Webhook commands

Dotfiles commands

Project and group commands

Organization security policy commands

Identity commands

Configuration commands

Network troubleshooting

Shell completion

Version and updates

Related