@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

npm install -g @agentium/cli
# or use npx without installing:
npx @agentium/cli init my-bot

Confirm install:

agentium --version

Commands

agentium init <name> — scaffold a new project

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

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

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:

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

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:

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:

- 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 — manual walkthrough without the CLI
• Skills overview — the skill system the CLI manages
• Git-Installable Skills — what skills install is doing under the hood