# CLI (okctl)

> Install okctl, the Ownkube command-line interface. Connect your AWS account, ship deployments, tail logs, and pull connection details from your terminal.

`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

#### Homebrew

```sh
# macOS and Linux
brew install ownkube/tap/okctl
```

#### Binary

```sh
# 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
```

#### Source

```sh
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](https://github.com/ownkube/ownkube-cli/releases/latest). The Homebrew install wires up shell completions automatically.

## Log in

1. **Authenticate**

   ```sh
   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`).

2. **Confirm**

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

#### Handoff

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

#### Autonomous

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

```sh
okctl aws list
okctl aws get <account-id>
```

Prefer the dashboard? The same flow is available in [**Settings > Cloud accounts**](https://app.ownkube.io/dashboard/settings). See [Connect your AWS account](/docs/guides/connect-aws) for the console walkthrough.

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

```sh
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](https://github.com/ownkube/ownkube-cli). It teaches your agent when `okctl` is the right tool and exactly which command to run for common tasks.

```sh
# 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.

---

**Don't see a feature you need?** Email [support@ownkube.io](mailto:support@ownkube.io?subject=Feature%20request). Ownkube is shaped by the teams using it and we ship what our users ask for.