# CLI Reference

Logos ADK exposes a single CLI entry point:

```bash
logos-adk --help
```

The current public CLI surface is grouped into four areas:

- runnable execution
- serving and storage
- quality and learning operators
- project and admin utilities

## Installation

Basic install:

```bash
pip install logos-adk
```

With optional interactive/serve features:

```bash
pip install "logos-adk[cli,tui,serve]"
```

## Core Commands

### Runnable commands

| Command | Purpose |
|---|---|
| `chat` | Interactive chat with a runnable from a config file |
| `run` | Run a runnable once with a prompt |
| `test` | Test runnable connectivity and basic execution |
| `validate` | Validate config syntax and structure |
| `describe` | Print a runnable summary without executing it |
| `tui` | Start the terminal IDE for a runnable config |

### Serving commands

| Command | Purpose |
|---|---|
| `serve` | Start the FastAPI server for one or more agents |
| `test-live` | Exercise a running HTTP server |
| `storage` | Run schema and migration commands for persistence backends |

### Quality and operator commands

| Command | Purpose |
|---|---|
| `quality` | Run quality suites and generate templates/schema |
| `integration` | Run integration suites from the CLI root |
| `regression` | Run regression suites from the CLI root |
| `load-test` | Run load-test suites from the CLI root |
| `judge-eval` | Run judge-eval suites from the CLI root |
| `retrieval` | Inspect retrieval-learning state |
| `tool-workflow` | Inspect tool/workflow learning state |
| `model-routing` | Inspect model-routing learning state |
| `evaluation` | Inspect continuous evaluation state |
| `improvement` | Inspect reward/policy/improvement state |
| `transfer` | Inspect and apply cross-agent learning transfers |

### Project and admin commands

| Command | Purpose |
|---|---|
| `project` | Project templates and project helpers |
| `upgrade` | Upgrade planning and release-management helpers |
| `admin` | Administrative import/export/cleanup commands |

## Common Usage

### Validate and run a config

```bash
logos-adk validate agent.yaml
logos-adk describe agent.yaml
logos-adk run agent.yaml "Hello"
logos-adk chat agent.yaml
```

### Start a local API server

```bash
logos-adk serve --agents agent.yaml --port 8000
```

With multiple agents:

```bash
logos-adk serve --agents agent-a.yaml --agents agent-b.yaml --host 127.0.0.1 --port 9000
```

With auth and startup validation:

```bash
logos-adk serve \
  --agents agent.yaml \
  --api-key my-secret-key \
  --require-workspace \
  --test
```

### Inspect a running server

```bash
logos-adk test-live --base-url http://127.0.0.1:8000 --agent assistant --prompt "hello"
logos-adk test-live --base-url http://127.0.0.1:8000 --agent assistant --prompt "stream me" --stream
```

### Run quality suites

```bash
logos-adk quality schema
logos-adk quality template > suite.yaml
logos-adk quality test --kind regression --config suite.yaml
logos-adk regression agent.yaml suite.yaml
logos-adk integration agent.yaml suite.yaml
logos-adk load-test agent.yaml suite.yaml
logos-adk judge-eval agent.yaml suite.yaml
```

### Storage and learning operators

SQLite-backed examples:

```bash
logos-adk evaluation scorecard --db-path .logos_adk/learning.db --workspace-id acme
logos-adk retrieval summary --db-path .logos_adk/retrieval_learning.db --workspace-id acme
```

PostgreSQL-backed examples:

```bash
logos-adk evaluation scorecard --dsn postgresql://user:pass@localhost/learning --workspace-id acme
logos-adk model-routing leaderboard --dsn postgresql://user:pass@localhost/routing --workspace-id acme
logos-adk retrieval summary --dsn postgresql://user:pass@localhost/retrieval --workspace-id acme
logos-adk tool-workflow tool-scores --dsn postgresql://user:pass@localhost/tool_workflow --workspace-id acme
```

Composite operator commands:

```bash
logos-adk improvement policy \
  --dsn postgresql://user:pass@localhost/learning \
  --model-routing-dsn postgresql://user:pass@localhost/routing \
  --retrieval-dsn postgresql://user:pass@localhost/retrieval \
  --tool-workflow-dsn postgresql://user:pass@localhost/tool_workflow \
  --workspace-id acme

logos-adk transfer artifacts \
  --dsn postgresql://user:pass@localhost/learning \
  --reflection-dsn postgresql://user:pass@localhost/reflection \
  --prompt-registry-dsn postgresql://user:pass@localhost/prompts \
  --retrieval-dsn postgresql://user:pass@localhost/retrieval \
  --tool-workflow-dsn postgresql://user:pass@localhost/tool_workflow \
  --model-routing-dsn postgresql://user:pass@localhost/routing \
  --source-agent-name support-bot
```

## Notes

- Prefer `logos-adk --help` and `<command> --help` for the source of truth when a new release changes flags.
- The public release gate validates the CLI through `bash scripts/quality_baseline.sh`.
- The CLI is intentionally split between root commands and operator groups so public contracts stay explicit.
