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

# @agentium/cli

> Scaffold, develop, and ship Agentium projects from your terminal

# @agentium/cli

The `agentium` command is the one-stop CLI for Agentium projects: scaffolding new apps, running a local dev server with auto-reload, installing skills from Git, and publishing your own skills.

## Install

```bash theme={null}
npm install -g @agentium/cli
# or use npx without installing:
npx @agentium/cli init my-bot
```

Confirm install:

```bash theme={null}
agentium --version
```

## Commands

### `agentium init <name>` — scaffold a new project

```bash theme={null}
agentium init my-bot
cd my-bot
npm install
npm run dev
```

What it creates:

```
my-bot/
├── package.json           # with @agentium/core, openai SDK, tsx
├── tsconfig.json          # NodeNext / strict
├── .env.example           # OPENAI_API_KEY placeholder
├── .gitignore             # node_modules, .env, .agentium/
├── README.md
└── src/
    ├── index.ts           # entry point with a sample Agent
    └── tools/
        └── example.ts     # sample defineTool
```

Flags:

| Flag                | Default   | Meaning                                                                                       |
| ------------------- | --------- | --------------------------------------------------------------------------------------------- |
| `--template <name>` | `default` | Pick a starter template (currently `default`, `transport-express`, `with-rag`, `with-skills`) |
| `--no-install`      | (off)     | Skip `npm install`                                                                            |
| `--git`             | (off)     | `git init` after scaffolding                                                                  |

### `agentium dev` — local dev server with reload

```bash theme={null}
agentium dev
```

What it does:

* Loads `src/index.ts` (or `entry` from `agentium.config.ts` if present)
* Watches `src/**` and restarts on changes (debounced 150ms)
* Streams agent output to the terminal with syntax-highlighted tool calls
* Exposes a local Express server with the agent at `POST /chat` (UI-Stream protocol) — convenient for testing with the Vercel AI SDK or any frontend

Flags:

| Flag             | Default        | Meaning                                           |
| ---------------- | -------------- | ------------------------------------------------- |
| `--port <n>`     | `3000`         | Server port                                       |
| `--entry <path>` | `src/index.ts` | Entry script                                      |
| `--no-server`    | off            | Don't start the HTTP server; just watch + restart |
| `--inspect`      | off            | Pass `--inspect` to Node for debugger attachment  |

### `agentium skills install <git-url>` — install a skill

```bash theme={null}
agentium skills install https://github.com/agentiumOS/skill-jq.git#v1.0.0
```

What it does:

* Clones the repo (or the `#ref` if specified) via `GitSkillLoader`
* Validates `SKILL.md` exists and parses cleanly
* Writes the skill metadata to `agentium.config.ts` under `skills`
* Adds the cache directory (`.agentium/skills/`) to `.gitignore`

The next `agentium dev` run loads the skill automatically.

Flags:

| Flag              | Default                 | Meaning                                   |
| ----------------- | ----------------------- | ----------------------------------------- |
| `--ref <tag>`     | (remote default branch) | Override the ref baked into the URL       |
| `--subdir <path>` | (none)                  | Path inside the repo where SKILL.md lives |
| `--force`         | off                     | Skip cache, re-clone                      |

### `agentium skills list`

List installed skills with their pinned ref:

```
agentium skills list

NAME          REF       URL
calculator    v1.0.0    https://github.com/agentiumOS/skill-jq.git
sql-runner    v0.3.2    https://github.com/agentiumOS/skill-sql.git
```

### `agentium skills publish` — publish a skill to a Git repo

For skill authors. Inside a directory with `SKILL.md`:

```bash theme={null}
agentium skills publish --tag v1.0.0
```

What it does:

* Validates `SKILL.md` shape (frontmatter, required keys)
* Runs any `agentium skills lint` checks (description length, script existence)
* Commits the working tree (if dirty), tags `v1.0.0`, pushes to the configured remote

Flags:

| Flag              | Default  | Meaning                            |
| ----------------- | -------- | ---------------------------------- |
| `--tag <name>`    | required | Tag to publish                     |
| `--remote <name>` | `origin` | Git remote                         |
| `--dry-run`       | off      | Validate and stage, but don't push |

### `agentium build` — type-check and bundle for production

```bash theme={null}
agentium build
```

Runs `tsc --noEmit` for typecheck, then bundles with esbuild into `dist/`. The output is a single CJS file that can be deployed to Node 20+, Cloudflare Workers, or any Edge runtime that ships Node-compat.

Flags:

| Flag             | Default  | Meaning           |
| ---------------- | -------- | ----------------- |
| `--target <env>` | `node20` | esbuild target    |
| `--outdir <dir>` | `dist`   | Output directory  |
| `--minify`       | off      | Minify the output |

## `agentium.config.ts`

Created on first `init`. Lets you configure the CLI commands without command-line flags:

```typescript theme={null}
import { defineConfig } from "@agentium/cli";

export default defineConfig({
  entry: "src/index.ts",
  dev: {
    port: 3000,
    watch: ["src/**", "skills/**"],
  },
  skills: [
    { name: "calculator", url: "https://github.com/agentiumOS/skill-jq.git", ref: "v1.0.0" },
  ],
  build: {
    target: "node20",
    outdir: "dist",
  },
});
```

All CLI flags override the corresponding config fields.

## Environment variables

The CLI reads `.env` (and `.env.local`) at startup via `dotenv`. Common keys:

| Key                                         | Used by               |
| ------------------------------------------- | --------------------- |
| `OPENAI_API_KEY`                            | OpenAI provider       |
| `ANTHROPIC_API_KEY`                         | Anthropic provider    |
| `COHERE_API_KEY`                            | CohereReranker        |
| `VOYAGE_API_KEY`                            | VoyageReranker        |
| `E2B_API_KEY`                               | E2BSandboxToolkit     |
| `DAYTONA_API_KEY`                           | DaytonaSandboxToolkit |
| `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD` | Neo4jCypherStore      |

## CI integration

The CLI is friendly to non-interactive use:

```yaml theme={null}
- name: Lint skills
  run: npx agentium skills lint --strict

- name: Build
  run: npx agentium build
```

All commands exit with code `0` on success and non-zero on any failure. `--strict` mode upgrades warnings to errors where applicable.

## Templates roadmap

Planned templates for `agentium init`:

* `transport-express` — Express app with `pipeAgentUIStreamToResponse`
* `transport-next` — Next.js Route Handler with Vercel UI Stream
* `with-rag` — InMemoryVectorStore + sample docs + reranker
* `with-skills` — Pre-wired skill manager + git-installable skill loader
* `with-mcp` — Sample MCP server + connected client agent
* `sandbox-agent` — SandboxAgent with E2B backend

`agentium init --template <name>` is forward-compatible — new templates land without a CLI version bump.

## See also

* [Quickstart](/quickstart) — manual walkthrough without the CLI
* [Skills overview](/skills/overview) — the skill system the CLI manages
* [Git-Installable Skills](/skills/git-skills) — what `skills install` is doing under the hood