# VeilCLI

**Enterprise autonomous agent runtime — local, API-first, multi-model.**

VeilCLI lets you define AI agents as simple files, run them as a local REST server, and control them through a clean HTTP API or interactive CLI. Agents can chat, run multi-step tool work inside a turn, spawn sub-agents, and maintain persistent memory — all without external services.

---

## Key Features

- **Chat agents + sub-agents** — converse with agents and spawn sub-agents via `agent_spawn`
- **24 built-in tools** — bash, file I/O, web search/fetch, memory, multi-agent communication, todos, and more
- **Persistent memory** — per-agent and project-wide Markdown memory files
- **Multi-agent orchestration** — parallel fan-out, durable subscriptions, sync/async spawning
- **Layered config** — global → project → local → CLI flags
- **Multi-provider routing** — configure multiple providers (OpenRouter, Anthropic, Claude CLI, Ollama, etc.) and route models per role
- **Any OpenAI-compatible LLM** — OpenRouter, local Ollama, Azure, etc.
- **Zero external dependencies** — SQLite storage, native fetch, Node.js only

---

## Requirements

- **Node.js ≥ 20.0.0**
- An OpenAI-compatible API key (e.g. [OpenRouter](https://openrouter.ai))

---

## Installation

```bash
npm install -g @newsails/veil-cli
```

---

## Quick Start

```bash
# 1. Set up a workspace
mkdir my-workspace && cd my-workspace

# 2. Save your API key (Optional)
veil login --key sk-or-v1-...

# 3. Start the server
veil start

# 4. Chat with the default agent
curl -X POST http://localhost:5050/agents/hello/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!"}'

# 5. Chat with tools
curl -X POST http://localhost:5050/agents/assistant/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "List all .js files in the current directory"}'
```

→ See **[docs/guide/01-quickstart.md](docs/guide/01-quickstart.md)** for the full walkthrough.

---

## Documentation

### API Reference
| Doc | Contents |
|-----|----------|
| [docs/api/README.md](docs/api/README.md) | Overview, auth, error codes |
| [docs/api/01-system.md](docs/api/01-system.md) | `/health`, `/status`, `/shutdown` |
| [docs/api/02-agents.md](docs/api/02-agents.md) | List and inspect agents |
| [docs/api/03-chat.md](docs/api/03-chat.md) | Chat endpoint, multi-turn sessions |
| [docs/api/05-sessions.md](docs/api/05-sessions.md) | Session management and messages |

### Project Guide
| Doc | Contents |
|-----|----------|
| [docs/guide/README.md](docs/guide/README.md) | Guide index |
| [docs/guide/01-quickstart.md](docs/guide/01-quickstart.md) | Install, first agent, first request |
| [docs/guide/02-folder-structure.md](docs/guide/02-folder-structure.md) | `.veil/` layout explained |
| [docs/guide/03-configuration.md](docs/guide/03-configuration.md) | `settings.json` + `auth.json` full reference |
| [docs/guide/04-agents.md](docs/guide/04-agents.md) | `agent.json`, `AGENT.md`, all 4 modes |
| [docs/guide/05-cli.md](docs/guide/05-cli.md) | `veil` CLI commands reference |
| [docs/guide/06-tools.md](docs/guide/06-tools.md) | All 24 built-in tools |
| [docs/guide/07-permissions.md](docs/guide/07-permissions.md) | Permissions system |
| [docs/guide/08-memory.md](docs/guide/08-memory.md) | Memory + context compaction |
| [docs/guide/09-multi-agent.md](docs/guide/09-multi-agent.md) | Orchestration patterns |

---

## CLI Reference (Quick)

```
veil start [--port 5050] [--folder ./workspace] [--secret <token>]
veil stop
veil status
veil agents list
veil agents inspect <name>
veil login --key <api-key> [--global]

# Talk to the instance already running in this project:
veil send "<message>" (--session <id> | --agent <name>)   # fire-and-forget
veil sessions [--agent <name>]                            # list sessions
veil state --session <id>                                 # inspect a session
veil suspend --session <id>                               # park a session
veil resume  --session <id>                               # reactivate it
```

→ Full reference: [docs/guide/05-cli.md](docs/guide/05-cli.md)

---

## Project Layout

```
VeilCli/
  cli/          ← Veil CLI entry point
  api/          ← Express REST server + routes
  core/         ← agent loader, loop, router, memory, compaction
  engines/      ← provider-specific LLM adapters (claude-cli engine)
  tools/        ← 24 built-in tools
  infrastructure/ ← SQLite database
  utils/        ← settings, paths, context
  schemas/      ← JSON schemas for agent.json and settings.json
  system-prompts/ ← base system prompt layers
  examples/     ← reference agent definitions
```

---

## License

MIT