CLI (okctl)

okctl is the Ownkube CLI. It drives the platform from your terminal: connect an AWS account, inspect clusters and deployments, tail logs, and pull in-cluster connection details. It is scriptable, agent-friendly, and every read command speaks JSON.

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.

Connect an AWS account

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.

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

okctl aws list
okctl aws get <account-id>

Common commands

Group	What it does
`okctl login` / `logout` / `status`	Browser-based auth and credential management
`okctl aws connect\|list\|get\|verify\|reconnect\|resync\|delete`	Connect an AWS account and manage its access
`okctl clusters list\|get`	Inspect clusters
`okctl environments list\|get`	Inspect environments
`okctl deploy list\|get\|status\|logs\|revisions\|connection`	Inspect deployments
`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)

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.

Use okctl with AI 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.