CLI - dotagents

Usage

dotagents [--user] <command> [options]

Global Options

--user Operate on user scope (~/.agents/) instead of the current project
--help, -h Show help
--version, -V Show version

Commands

`dotagents init`

dotagents init [--agents claude,cursor] [--force]

Initialize a new project with agents.toml and .agents/skills/. Interactive mode prompts for agent targets and trust policy. Sets up gitignore entries automatically.

--agents <list> Comma-separated agent targets (claude, cursor, codex, vscode, opencode)
--force Overwrite existing agents.toml

dotagents init
dotagents init --agents claude,cursor
dotagents --user init

`dotagents install`

dotagents install [--force]

Install all skill dependencies from agents.toml. Resolves sources, copies skills, writes lockfile, creates symlinks, generates MCP and hook configs. Always fetches latest unless a ref is pinned.

--force Re-resolve and re-install all skills, ignoring cache

dotagents install
dotagents install --force    # bypass cache

`dotagents add`

dotagents add <source> [--name <name>] [--ref <ref>] [--all]

Add a skill dependency and install it. Auto-discovers skills in the repo. When a repo has one skill, it is added automatically. When multiple are found, use --name to pick one or --all to add them all as a wildcard entry. Shorthand owner/repo resolves via defaultRepositorySource in agents.toml.

--name <name> Specify which skill to add (alias: --skill)
--ref <ref> Pin to a specific tag, branch, or commit
--all Add all skills from the source as a wildcard entry (name = "*")

# Single skill from GitHub
dotagents add getsentry/skills --name find-bugs

# All skills from a repo
dotagents add getsentry/skills --all

# Pinned to a version
dotagents add getsentry/warden@v1.0.0

# Explicit GitLab URL
dotagents add https://gitlab.com/group/repo --name find-bugs

# Non-GitHub git server
dotagents add git:https://git.corp.dev/team/skills --name review

# Local directory
dotagents add path:./my-skills/custom

`dotagents remove`

dotagents remove <name>

Remove a skill from agents.toml, delete from disk, and update the lockfile. For wildcard-sourced skills, adds to the exclude list instead of removing the entire wildcard entry.

dotagents remove find-bugs

`dotagents sync`

dotagents sync

Reconcile project state without network access. Adopts orphaned skills, regenerates gitignore, repairs symlinks and MCP/hook configs. Reports issues as warnings or errors.

`dotagents mcp add`

dotagents mcp add <name> --command <cmd> [--args <a>...] [--env <VAR>...] dotagents mcp add <name> --url <url> [--header <Key:Value>...] [--env <VAR>...]

Add an MCP server declaration to agents.toml and run install to generate agent configs. Specify exactly one transport: --command for stdio or --url for HTTP.

--command <cmd> Command to execute (stdio transport)
--args <arg> Command argument (repeatable)
--url <url> Server URL (HTTP transport)
--header <Key:Value> HTTP header (repeatable, url servers only)
--env <VAR> Environment variable name to pass through (repeatable)

# Stdio server
dotagents mcp add github --command npx --args -y --args @modelcontextprotocol/server-github --env GITHUB_TOKEN

# HTTP server with auth header
dotagents mcp add remote --url https://mcp.example.com/sse --header Authorization:Bearer\ tok

`dotagents mcp remove`

dotagents mcp remove <name>

Remove an MCP server declaration from agents.toml and run install to regenerate agent configs.

dotagents mcp remove github

`dotagents mcp list`

dotagents mcp list [--json]

Show declared MCP servers. Use --json for machine-readable output.

dotagents mcp list
dotagents mcp list --json

`dotagents trust add`

dotagents trust add <source>

Add a trusted source to [trust] in agents.toml. The type is inferred automatically: owner/repo for repos, names with . for domains, and bare names for GitHub orgs.

dotagents trust add getsentry
dotagents trust add external-org/specific-repo
dotagents trust add git.corp.example.com

`dotagents trust remove`

dotagents trust remove <source>

Remove a trusted source from [trust] in agents.toml. Matching is case-insensitive.

dotagents trust remove getsentry

`dotagents trust list`

dotagents trust list [--json]

Show trusted sources with their type. Use --json for machine-readable output.

dotagents trust list
dotagents trust list --json

`dotagents doctor`

dotagents doctor [--fix]

Check project health and fix issues. Verifies gitignore setup, installed skills, symlinks, and detects legacy config fields. Useful for migrating to a new version of dotagents.

--fix Auto-fix issues where possible

dotagents doctor          # check for issues
dotagents doctor --fix    # fix what it can

`dotagents list`

dotagents list [--json]

Show installed skills and status. Use --json for machine-readable output.

✓ Installed and present in lockfile
✗ In config but not installed
? Installed but not in lockfile

Source Formats

Format	Example	Description
GitHub	`getsentry/skills`	Auto-discovers skills by name
Pinned	`getsentry/skills@v1.0.0`	Locked to a specific ref
Git URL	`git:https://git.corp.dev/repo`	Non-GitHub git servers
Local	`path:./my-skills/custom`	Local directory, relative to project root

Configuration (agents.toml)

Top-level Fields

Field	Type	Default	Description
`version`	integer	--	Schema version. Always `1`.
`agents`	string[]	`[]`	Agent targets: `claude`, `cursor`, `codex`, `vscode`, `opencode`
`defaultRepositorySource`	string	`github`	Host used for shorthand `owner/repo` sources. Valid values: `github` or `gitlab`.

Skills

Field	Type	Required	Description
`name`	string	Yes	Skill identifier. Use `"*"` for wildcard.
`source`	string	Yes	`owner/repo`, `owner/repo@ref`, GitHub/GitLab URL, `git:url`, or `path:relative`
`ref`	string	No	Tag, branch, or commit SHA to pin
`path`	string	No	Subdirectory within repo (when auto-discovery fails)
`exclude`	string[]	No	Skills to skip (wildcard entries only)

MCP Servers

Field	Type	Required	Description
`name`	string	Yes	Unique server identifier
`command`	string	Stdio	Command to execute
`args`	string[]	No	Command arguments
`url`	string	HTTP	Server URL
`headers`	table	No	HTTP headers (url servers only, not needed with OAuth)
`env`	string[]	No	Environment variable names to pass through

Hooks

Field	Type	Required	Description
`event`	string	Yes	`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`
`matcher`	string	No	Tool name filter
`command`	string	Yes	Shell command to execute

Scopes

Project Scope (default)

Operates on the current project. Requires agents.toml at the project root. Skills go to .agents/skills/, lockfile to agents.lock.

User Scope (--user)

Manages skills shared across all projects. Files live in ~/.agents/ (override with DOTAGENTS_HOME). Symlinks go to ~/.claude/skills/ and ~/.cursor/skills/.

dotagents --user init
dotagents --user add getsentry/skills --all
dotagents --user install

When no agents.toml exists and you are not inside a git repo, dotagents falls back to user scope automatically.

Environment Variables

Variable	Description
`DOTAGENTS_STATE_DIR`	Override cache location (default: `~/.local/dotagents`)
`DOTAGENTS_HOME`	Override user-scope location (default: `~/.agents`)