CLI (okctl)
okctl is the Ownkube command-line interface. It does everything the dashboard does from a terminal: deploy a directory, read logs and metrics, open a shell, connect to a database, manage alerts, projects and billing. Every command takes -o json, which is what makes it the easiest way for a coding agent to drive Ownkube.
Install
Section titled “Install”brew install ownkube/tap/okctlWorks on macOS and Linux with Homebrew. brew upgrade okctl later.
Download the archive for your platform from the releases page and put okctl on your PATH. For example, on Apple silicon:
curl -L https://github.com/ownkube/ownkube-cli/releases/latest/download/ownkube-cli_darwin_arm64.tar.gz | tar xzsudo mv okctl /usr/local/bin/go install github.com/ownkube/okctl@latestNeeds a current Go toolchain. The binary lands in $(go env GOPATH)/bin.
Check it with okctl version. Shell completion is one command away: okctl completion zsh (or bash, fish, powershell) prints the script to install.
Sign in
Section titled “Sign in”okctl loginA browser tab opens for you to sign in and pick an organization; the terminal picks up the session when you return. Credentials are stored in ~/.config/ownkube/credentials.yaml with owner-only permissions. okctl status shows who you are signed in as, and okctl logout clears it.
Link a directory
Section titled “Link a directory”cd my-appokctl linkokctl link binds the current directory to an organization, environment and deployment, so later commands can infer their target. Run it with no flags for an interactive picker, or pass --organization, --environment and --service to link non-interactively in CI. The binding lives in your global config, never in the repository, so nothing is committed. okctl unlink removes it.
Linked commands such as okctl up, okctl ssh and okctl connect then work with no arguments. Unlinked, pass the deployment id or --service.
Deploy with okctl up
Section titled “Deploy with okctl up”okctl upokctl up archives the working tree (uncommitted changes included, files ignored by .gitignore left out), uploads it, builds it and follows the rollout until the app is live. In a directory that is not linked yet it creates a new web app on Ownkube Compute with sensible defaults, prints what it chose, and links the directory so the next okctl up redeploys it.
| Flag | Default for a new app |
|---|---|
--name | the directory name, made unique |
--region | the region you already use; ids from okctl regions list |
--port | the Dockerfile EXPOSE, else the framework default, else 8080 |
--type | web (or worker) |
--public | true, a public URL |
--project, --environment | your default project and its default environment |
Add --note "..." to record a note on the revision, --path to deploy another directory, and --no-follow to return as soon as the build is queued. Builds from source bill build minutes.
Output and configuration
Section titled “Output and configuration”Every read command prints a table by default and structured data with -o json or -o yaml:
okctl deploy list -o json | jq '.[] | {name, status}'| Setting | Flag | Environment variable | Config key |
|---|---|---|---|
| API endpoint | --api-url | OKCTL_API_URL | apiUrl |
| Output format | -o, --output | outputFormat |
okctl config view prints the stored configuration, okctl config set outputFormat json changes a value, okctl config get <key> reads one.
Use okctl with coding agents
Section titled “Use okctl with coding agents”A skill that teaches Claude Code, Cursor, Codex, Copilot and similar agents when and how to run okctl ships in the CLI repository. Install it into the current project, or globally with -g:
npx skills add ownkube/ownkube-clinpx skills add ownkube/ownkube-cli -gThe skill covers deploy diagnostics, logs, connection details and name-to-id lookups, and leans on -o json so the agent reads structured output. If you would rather give the agent tools than a terminal, the hosted MCP server exposes the same API.