> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nasiko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI usage reference

> Command reference for the nasiko developer CLI.

`nasiko` builds, tests, deploys, and monitors agents against a control plane. See [CLI installation](/cli/setup) to install it and the [quickstart](/quickstart) for the core workflow.

State lives in `~/.nasiko/config.json` (clusters, active cluster, tokens) and `~/.nasiko/.env` (local-stack config).

<Note>
  Every command operates against the **active cluster**, selected with `nasiko use <name>`. Run `nasiko <command> --help` for full flags.
</Note>

## Setup

| Command                                              | Purpose                                             |
| ---------------------------------------------------- | --------------------------------------------------- |
| `nasiko up`                                          | Start a full local platform (infra + control plane) |
| `nasiko down`                                        | Stop the local platform                             |
| `nasiko connect <url> [--name <name>]`               | Register a control plane by URL                     |
| `nasiko use <name>`                                  | Switch the active cluster                           |
| `nasiko clusters`                                    | List registered control planes                      |
| `nasiko status`                                      | Active cluster's health and metrics                 |
| `nasiko auth login` / `status` / `logout` / `whoami` | Authentication                                      |

```bash theme={null}
nasiko connect https://nasiko.example.com --name prod
nasiko use prod
nasiko auth login
```

## Create

| Command                                    | Purpose                                                           |
| ------------------------------------------ | ----------------------------------------------------------------- |
| `nasiko new [template] [name]`             | Scaffold a new agent project (interactive if template is omitted) |
| `nasiko skill add/remove/list/search/info` | Manage agent skills (tools) attached to a project                 |
| `nasiko card [description] [--dir <dir>]`  | Generate or update `AgentCard.json`                               |
| `nasiko validate [dir]`                    | Check `AgentCard.json`, `Dockerfile`, and `src/` are in order     |

```bash theme={null}
nasiko new                          # interactive: pick a framework
nasiko new openai my-agent          # skip the prompts
nasiko validate ./my-agent
```

## Test

| Command                                                                                       | Purpose                                               |
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `nasiko build [dir] [--tag <tag>] [--platform <platform>]`                                    | Build the agent's Docker image                        |
| `nasiko run [dir] [--port <port>]`                                                            | Build and run the agent locally (default port `8000`) |
| `nasiko chat [target] [message] [--agent <name>] [--tui] [--session-id <id>] [--resume <id>]` | Send an A2A message                                   |
| `nasiko sessions` / `create-session` / `history` / `delete-session`                           | Manage chat sessions                                  |

```bash theme={null}
nasiko run .                                   # build + run on :8000
nasiko chat http://localhost:8000 "hello"      # talk to the local instance directly
nasiko chat --tui                              # full-screen chat TUI
```

`nasiko chat`'s target can be a URL, an agent name or UUID, or `orchestrator`. Omit it to talk to the routing engine. A lone argument containing whitespace is treated as the message, not the target.

## Operate

| Command                                                                                           | Purpose                                                                        |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `nasiko push <image> [--name <name>]`                                                             | Build + push an image to the cluster registry (no deploy)                      |
| `nasiko deploy <image-or-dir> [--name <name>] [--port <port>] [--env-file <file>] [-e KEY=VALUE]` | Build + push + deploy                                                          |
| `nasiko upload [source] [--name <name>] [--version <v>] [--port <port>]`                          | Upload source; the server builds and deploys it                                |
| `nasiko ps`                                                                                       | List running agents                                                            |
| `nasiko logs <agent> [-n <count>] [-f]`                                                           | Stream agent logs (`-f` live-tails via SSE)                                    |
| `nasiko stop/start/restart <agent>`                                                               | Lifecycle control (`restart` picks up new secrets/env)                         |
| `nasiko scale <agent> <replicas>`                                                                 | Scale to N replicas                                                            |
| `nasiko rm --name <agent>`                                                                        | Terminate and deregister (accepts a raw UUID positionally instead of `--name`) |
| `nasiko secrets set/get/ls/rm [--agent <name>]`                                                   | Encrypted secrets (vault-wide, or per agent)                                   |
| `nasiko observe sessions/session/trace-detail/span/...`                                           | Traces, tokens, and cost                                                       |

```bash theme={null}
nasiko deploy . --port 8000 -e LOG_LEVEL=debug
nasiko logs my-agent -f
nasiko scale my-agent 3
nasiko secrets set OPENAI_API_KEY sk-... --agent my-agent
nasiko observe session <session-id>
```

Pass an image reference instead of a directory to `nasiko deploy` to skip the build. `nasiko push` builds and pushes **without starting** the container — it does still register a `registered`-status catalog entry for the agent (visible in `nasiko ps`/`agents ls`), it just never runs.

## Multi-agent

| Command                                                                                | Purpose                                                                  |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `nasiko maf workflow create --name <name> --step <task> [--agent <name\|uuid\|->] ...` | Define a workflow (repeat `--step`/`--agent` per step; `-` auto-assigns) |
| `nasiko maf workflow run <id-or-name> [--wait]`                                        | Queue an execution                                                       |
| `nasiko maf workflow get <id>`                                                         | Read one workflow                                                        |
| `nasiko maf execution list` / `get <id>` / `result <id>`                               | Inspect executions                                                       |

```bash theme={null}
nasiko maf workflow create --name "research-and-summarize" \
  --step "Research recent news on topic X" --agent research-agent \
  --step "Summarize the research into 3 bullet points" --agent -   # "-" auto-assigns
nasiko maf workflow run research-and-summarize --wait
nasiko maf execution result <execution-id> --json
```

Full flag reference: `nasiko maf --help`. See [MAF](/platform/maf) for the workflow model and REST API.

## LLM configuration

| Command                                         | Purpose                                                         |
| ----------------------------------------------- | --------------------------------------------------------------- |
| `nasiko llm-config providers/create/attach/get` | Per-agent named LLM configs (provider, model, fallback, tuning) |
| `nasiko model-registry ls/set`                  | Platform-wide strength-level → model table (requires superuser) |

```bash theme={null}
nasiko llm-config create --name support-cheap --provider openai --model gpt-4o-mini
nasiko llm-config attach support-bot support-cheap
```

Full command set: `nasiko llm-config --help`. See [routing engine](/platform/llm-router) for how these fit into agent selection.

## Integrations

| Command                                                                                    | Purpose                                              |
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| `nasiko agents ls/get/deploy/search/info/frameworks/list-uploaded/chat`                    | Agent registry + lifecycle operations                |
| `nasiko github status/repos/connect/disconnect/clone`                                      | GitHub OAuth connection + clone-to-deploy            |
| `nasiko registry connect/disconnect/status/search/list`                                    | Connect to and browse the artifact registry          |
| `nasiko mcp catalog/connect/connections/disconnect/connector/credential/oauth/agent-tools` | MCP Gateway connector and tool-permission management |

```bash theme={null}
nasiko github clone myorg/my-agent-repo
nasiko registry search "invoice processing"
nasiko mcp catalog
nasiko mcp connect --toolkit <name>       # from the catalog output
```

## What you're connecting to

| Entity                | What it is                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| Control plane         | Deploys agents, routes queries, proxies A2A traffic, serves the observability and registry APIs   |
| Embedded OCI registry | The control plane's `/v2/*` endpoint — stores your deployed agent images                          |
| Artifact registry     | A separate service for templates and skills, used by `nasiko new`, `skill search`, and `registry` |

The CLI only operates on agents you own or have been granted. See [access control](/onboarding/acl/overview).