CLI (okctl)

okctl is the Ownkube CLI. It drives the platform from your terminal: inspect deployments, tail logs, check status, and pull connection details. It is scriptable, and every read command speaks JSON. If you run in your own AWS account (the Advanced path), it also connects and manages that account.

Install

# macOS and Linux
brew install ownkube/tap/okctl

# macOS arm64 example
curl -sSL https://github.com/ownkube/ownkube-cli/releases/latest/download/ownkube-cli_darwin_arm64.tar.gz \
  | tar -xz -C /usr/local/bin okctl

go install github.com/ownkube/okctl@latest

Pre-built binaries are published for darwin/amd64, darwin/arm64, linux/amd64, linux/arm64, windows/amd64, and windows/arm64 on the latest release. The Homebrew install wires up shell completions automatically.

Log in

Authenticate
Terminal window
```
okctl login
```
This opens your browser, authorizes the CLI against your Ownkube account, and stores an API key at ~/.config/ownkube/credentials.yaml (file mode 0600).
Confirm
Terminal window
```
okctl status
```
Shows the signed-in user and the API URL in use.

Common commands

Group	What it does
`okctl login` / `logout` / `status`	Browser-based auth and credential management
`okctl deploy list\|get\|status\|logs\|revisions\|connection`	Inspect deployments
`okctl environments list\|get`	Inspect environments
`okctl registries list\|get`	Inspect container registries
`okctl organizations list`	List organizations you belong to
`okctl completion <shell>`	Generate shell completion (bash, zsh, fish, powershell)

For the own-cloud (Advanced) commands, okctl aws ... and okctl clusters ..., see Own cloud (Advanced) below.

Run okctl <command> --help for flags and arguments.

Machine-readable output

Add -o json (or -o yaml) to any read command for structured output:

okctl deploy get <deployment-id> -o json | jq .

Configuration

okctl resolves settings in this order (highest priority first):

Setting	Flag	Env var	Config file	Default
API URL	`--api-url`	`OKCTL_API_URL`	`apiUrl` in `config.yaml`	`https://app.ownkube.io`
Output format	`-o, --output`		`outputFormat` in `config.yaml`	`table`

Config files live in ~/.config/ownkube/: config.yaml for preferences and credentials.yaml (mode 0600) for your API key.

Own cloud (Advanced)

Only needed if you run in your own AWS account. On Ownkube-hosted compute there’s nothing here to set up.

okctl aws connect onboards an AWS account end to end. The CloudFormation stack you deploy grants Ownkube a scoped, least-privilege cross-account role and phones home when it is ready. Ownkube never receives your AWS keys.

Handoff
Headless

# Opens the AWS console to a quick-create form, then waits for verification
okctl aws connect

# Deploys the stack with the AWS credentials already in your shell.
# Requires the AWS CLI. Ideal for headless or agent use.
okctl aws connect --deploy

connect polls until the account is verified. Useful flags:

Flag	Effect
`--deploy`	Create the stack with your local AWS credentials instead of the browser
`--no-wait`	Return once onboarding has started; do not poll
`--no-browser`	Print the quick-create URL without opening it
`--timeout`	How long to wait for verification (default 15m)
`-o json`	Return the full payload (external ID and stack template) for scripting

Check status any time, and inspect the clusters running in your account:

okctl aws list
okctl aws get <account-id>
okctl clusters list
okctl clusters get <cluster-id>

Use okctl with coding agents

A skill for Claude, Cursor, Codex, Copilot, and Cline ships in the CLI repo. It teaches your agent when okctl is the right tool and exactly which command to run for common tasks.

# Into the current project
npx skills add ownkube/ownkube-cli

# Globally, across all projects
npx skills add ownkube/ownkube-cli -g

Then ask your agent things like “deploy my app to Ownkube” or “why is my Ownkube deployment failing?” and it will drive okctl for you.