npm package: @newsails/veil-cli
Description: VeilCLI - Enterprise autonomous agent runtime — local, API-first, multi-model
Latest version: 1.0.1

# 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 tasks with tools, spawn sub-agents, schedule cron jobs, and maintain persistent memory — all without external services.

---

## Key Features

- **4 agent modes** — Chat, Task, Daemon (cron), Subagent
- **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
- **Any OpenAI-compatible LLM** — OpenRouter, local Ollama, Azure, etc.
- **Zero external dependencies** — SQLite storage, native fetch, Node.js only

---

## Requirements

- **Node.js ≥ 18.3.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. Run a task with tools
curl -X POST http://localhost:5050/agents/assistant/task \
  -H "Content-Type: application/json" \
  -d '{"input": "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/04-tasks.md](docs/api/04-tasks.md) | Task lifecycle, events, polling |
| [docs/api/05-sessions.md](docs/api/05-sessions.md) | Session management and messages |
| [docs/api/06-daemons.md](docs/api/06-daemons.md) | Daemon control endpoints |

### 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 |
| [docs/guide/10-daemons.md](docs/guide/10-daemons.md) | Daemon / cron agents |

---

## CLI Reference (Quick)

```
veil start [--port 5050] [--folder ./workspace] [--secret <token>]
veil run --agent hello --input "What time is it?"
veil stop
veil status
veil agents list
veil agents inspect <name>
veil login --key <api-key> [--global]
```

→ 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
  tools/        ← 24 built-in tools
  infrastructure/ ← SQLite database + scheduler
  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