An agent is a folder: a .description manifest, a .behavior state machine, an optional persona, and the knowledge it teaches. This CLI turns that folder into a single portable .agent file, and runs one back.

$ npm install -g @dot-agent/cli
$ mkdir my-agent && cd my-agent
$ dot-agent init --name my-agent --domain example.com
✓ Scaffolded agent project in /tmp/my-agent
  Files: LICENSE, README.md, SOUL.md, agent.behavior, agent.description,
         behaviors/.gitkeep, guides/.gitkeep, knowledge/.gitkeep

$ dot-agent pack --dir . --out my-agent.agent
✓ Packed → my-agent.agent
  ID: example.com/my-agent
  Warnings: 1
⚠ agent.description:2:10 W003 domain still has default value "example.com"

The warning is the point: pack lints before it writes, so a broken agent fails at authoring time rather than at run time.

Install

npm install -g @dot-agent/cli

Or run it without installing:

npx @dot-agent/cli <command>

Commands

| Command | What it does | |---|---| | dot-agent init [--name <name>] [--domain <domain>] [--dir <dir>] [--force] | Scaffold an agent project | | dot-agent pack [--dir <dir>] [--out <file>] [--version <tag>] [--commit <hash>] | Lint and package into a .agent archive | | dot-agent unpack <file.agent> [--out <dir>] [--force] | Extract an .agent back to editable sources | | dot-agent run <file.agent \| dir> | Load an agent and start its state machine | | dot-agent run <src> --mcp | Serve a loaded agent over MCP | | dot-agent run --helper | Serve the interactive authoring helper over MCP | | dot-agent configure --claude | Install the native Claude Code plugin and remove any legacy MCP entries this CLI wrote before | | dot-agent configure [--gemini] [--agy] [--murici] [--skill] [--mcp] | Write the skill file and/or MCP config directly, for hosts with no dot-agent plugin (yet) | | dot-agent server-mcp | Serve the authoring tools over MCP | | dot-agent agents list · agents path <name> | List installed agents, or resolve one to a path |

The MCP commands take --mcp-transport stdio|http and --mcp-port <n>.

init writes into the current directory unless you pass --dir. It refuses to start when any file it would write already exists — naming every collision at once, before writing anything — so pointing it at a populated folder is safe. Pass --force to overwrite them deliberately.

Without --version, pack prompts for one in a terminal and packs versionless otherwise; it never invents a default.

Use as a library

Every command is also an exported function, for embedding in a Node or Electron host:

import { pack, run } from '@dot-agent/cli'

const packed = await pack({ dir: './my-agent', out: './my-agent.agent' })
console.log(packed.id, packed.path, packed.warnings.length)

const { bundle, session } = await run({ source: './my-agent.agent' })

Also exported: init, unpack, configure, listAgents, getAgentPath, startDevMcpServer, and the AgentBundle / PackResult / LintMessage types.

Writing an agent

The .description and .behavior formats, the memory model and the full lint-code list are the language specification, not CLI surface:

• Language reference — .description, .behavior, types, memory
• Lint codes — every E/W code pack can raise
• .agent package format — archive layout and aboutme.json

Or let the CLI teach you interactively: dot-agent run --helper starts an agent whose whole purpose is explaining how to write one.

Requirements

Node.js 24 or newer.

License

Copyright (c) 2026 Danilo Borges. Licensed under the Apache License 2.0 — see LICENSE.