---
title: AKOS CLI
description: Set up the akos command line, run your first health check, and configure shell completion.
---

The AKOS CLI (`akos`) lets you manage every part of your AKOS workspace from a terminal: initialize workspaces, run flows, manage agents, configure triggers, operate secrets, and deploy plugins — all scriptable and CI-friendly.

## Requirements

- An active AKOS workspace (self-hosted desktop or cloud tenant)
- Credentials for that workspace from your AKOS administrator

## Installation

The `akos` CLI is provided as part of your AKOS enterprise plan. Your administrator distributes the build for your platform and your CI environment. If you don't have it yet, contact your AKOS administrator or account team for access.

Once it's installed, confirm it's available:

```bash
akos --version
```

## First run: doctor

Before doing anything else, run the built-in diagnostics to confirm the CLI is configured correctly:

```bash
akos doctor
```

`doctor` checks:

- Node.js version compatibility
- Platform support
- Whether the core AKOS runtime is linked
- The `AGENTSKITOS_HOME` data directory
- Available trigger kinds

To also verify that your AI provider credentials are present (no secret values are printed):

```bash
akos doctor --creds
```

To run a live connectivity probe (LLM round-trip + sandbox check, 10-second timeout):

```bash
akos doctor --live
```

### doctor options

| Flag | Description |
|---|---|
| `--live` | Run live LLM and sandbox probes |
| `--creds` | Check AI provider credential presence |
| `--air-gap` | Skip cloud providers when checking credentials |
| `--provider <id>` | Restrict credential check to one provider (repeatable) |
| `--env-prefix <pfx>` | Environment variable prefix to scan (default: `AGENTSKITOS_`) |
| `--secrets-file <path>` | Merge key names from a dotenv-style file into the credentials check |
| `--no-probes` | Skip vault and keychain probes |
| `--init-audit-key <wsId>` | Pre-generate an ed25519 audit signing key for a workspace and exit |

## Getting help

Every command and subcommand accepts `--help`:

```bash
akos --help
akos run --help
akos config validate --help
```

## Shell completion

Generate and install a completion script for your shell so you can tab-complete commands and flags.

**Bash** — add to `~/.bashrc`:

```bash
eval "$(akos completion bash)"
```

**Zsh** — add to `~/.zshrc`:

```bash
eval "$(akos completion zsh)"
```

**Fish** — save to the completions directory:

```bash
akos completion fish > ~/.config/fish/completions/akos.fish
```

Supported shells: `bash`, `zsh`, `fish`.

## Checking for updates

```bash
akos upgrade
```

To print the current and latest version without installing:

```bash
akos upgrade --check
```

## CI environments

When the environment variable `AKOS_TOKEN` is set, `auth login` is skipped automatically. This is the recommended pattern for non-interactive CI pipelines.

## Topic guides

Walkthroughs for the most common operator paths (each links to the full command table):

| Guide | Covers |
|---|---|
| [Authentication](/docs/cli/authentication) | Login, vault, secrets, creds |
| [Connections](/docs/cli/connections) | Setup registry, provision integrations, preflight |
| [Agents](/docs/cli/agents) | Registry, versions, promotion, compare |
| [Flows and Runs](/docs/cli/flows-and-runs) | Scaffold, run, watch, HITL, retention |
| [Processes (Pipelines)](/docs/cli/pipelines) | Multi-phase runs, resume, cancel |
| [Triggers](/docs/cli/triggers) | Cron, webhook, file-watch, sidecar ops |
| [Knowledge and RAG](/docs/cli/knowledge-and-rag) | Sources, search, prod seed, assistant docs |
| [Security and Governance](/docs/cli/security-governance) | Posture, firewall, audit, compliance |
| [Costs and Observability](/docs/cli/costs-observability) | Spend, usage limits, traces, tails |
| [Chat and shell](/docs/cli/chat) | Copilot one-shot, readline, TUI, slash commands |
| [Configuration](/docs/cli/configuration) | Validate, diff, lockfile, sync |
| [Migrating to AKOS](/docs/cli/migrating) | Import workflows, migrate-to-cloud |
| [Deploying](/docs/cli/deploying) | Plugins, sidecar, snapshots, telemetry |

## Reference

- [Using the App](/docs/using-the-app) — the same workspace from the browser or desktop UI
- [Command Reference](/docs/cli/command-reference) — every top-level command in one table