CLI

Usage

dotagents [--project|--global|--user] <command> [options]

Commands use global scope under ~/.agents/ when no scope flag is present, even inside a configured repository. The unqualified examples below are global.

Global Options

• --project operates on the containing Git repository, or the current directory outside Git.
• --global explicitly selects global scope.
• --user is a compatibility alias for --global.
• --help, -h shows help.
• --version, -V shows version.

Project commands other than init require agents.toml and never fall back to global state. Do not combine --project with --global or --user.

Commands

dotagents init

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

Initialize the selected scope’s config and managed directories. Interactive mode prompts for agent targets and trust policy. Project init also sets up gitignore entries.

By default, init declares the dotagents skill from getsentry/dotagents so agents can discover CLI guidance. It then runs install best-effort.

Options:

• --agents <list> comma-separated agent targets (claude, cursor, codex, vscode, opencode, grok, pi).
• --force overwrites existing agents.toml.

Examples:

dotagents init
dotagents init --agents claude,cursor
dotagents --project init

dotagents install

dotagents install

Install and refresh skill, subagent, and plugin dependencies from agents.toml. Resolves sources, copies canonical artifacts, writes the lockfile, creates symlinks, and generates MCP, hook, subagent, and plugin runtime configs. There is no separate update command. Plugins install into the active global or project scope. The deprecated --frozen flag prints a warning and performs the same normal install; use explicit ref values to pin sources.

Example:

dotagents install

dotagents add

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

Add and install plugins or skills. For git and local sources, dotagents discovers plugins first. If it finds any, the whole source is treated as plugin-only and skills in that source are ignored. Otherwise the existing skill discovery flow is used. Malformed plugin-shaped content fails without falling back to skills. Local plugin sources that overlap the project’s managed .agents/plugins directory are rejected before configuration changes. Well-known HTTPS catalogs are always skill-only. A single dependency is selected automatically; multiple dependencies use a picker in interactive mode.

Shorthand owner/repo resolves through defaultRepositorySource in agents.toml.

Options:

• --name <name> specifies which dependency to add. Repeatable.
• --skill <name> is a compatibility alias for --name and does not force skill mode.
• --ref <ref> pins to a specific tag, branch, or commit.
• --all writes every currently discovered plugin explicitly in plugin mode. In skill mode it adds the existing wildcard entry (name = "*"), which can include future upstream skills.

Plugin declarations record the exact discovered source path (. for a plugin at the source root), so later additions to the source cannot change selection. If config mutation or installation fails, add restores the previous agents.toml content rather than leaving a failed dependency declared. Exact repeats leave agents.toml unchanged and refresh installation; conflicting declarations still fail.

Do not mix positional names and --skill or --name flags in the same command.

Examples:

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

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

# One plugin from a repository plugin catalog
dotagents add getsentry/agent-plugins review-tools

# Snapshot every plugin currently in a local catalog
dotagents add path:./agent-plugins --all

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

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

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

# Well-known HTTPS source
dotagents add https://cli.sentry.dev error-tracking

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

dotagents remove

dotagents remove <name|source> [-y]

Remove a skill or plugin from agents.toml, delete managed installed files, and update the lockfile. You can also pass a source to remove all skills and plugins from that source. When removing a skill provided by a wildcard source, dotagents can add that skill to the wildcard exclude list. If a skill and plugin share the same name, name-based removal is rejected. When their sources differ, pass the dependency’s source to disambiguate.

Options:

• -y, --yes skips confirmation when removing by source or excluding a wildcard-provided skill.

Example:

dotagents remove find-bugs
dotagents remove getsentry/skills -y

dotagents sync

dotagents sync

Reconcile the selected scope without network access. Adopts local orphaned skills, prunes stale managed skills, subagents, and plugins removed from config, and repairs symlinks plus MCP, hook, subagent, and plugin configs. Project scope also regenerates managed gitignore state. Reports issues as warnings or errors.

dotagents mcp add

dotagents mcp add <name> --command "<cmd> [args...]" [--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.

Options:

• --command "<cmd> [args...]" is the command string to execute for stdio transport.
• --url <url> is the server URL for HTTP transport.
• --header <Key:Value> adds an HTTP header. Repeatable. URL servers only.
• --env <VAR> passes through an environment variable. Repeatable.

Examples:

# Stdio server
dotagents mcp add github --command "npx -y @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.

Example:

dotagents mcp remove github

dotagents mcp list

dotagents mcp list [--json]

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

Examples:

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.

When defaultRepositorySource = "gitlab", shorthand trust sources are stored as GitLab domain rules.

Examples:

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.

Example:

dotagents trust remove getsentry

dotagents trust list

dotagents trust list [--json]

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

Examples:

dotagents trust list
dotagents trust list --json

dotagents doctor

dotagents doctor [--fix]

Check the selected scope and fix supported issues. Verifies installed skills and plugins, plugin runtime projections, and legacy config fields. Project scope also checks gitignore setup, symlinks, and managed hooks. Use dotagents sync in the same scope to repair generated runtime configs.

Options:

• --fix auto-fixes issues where possible.

Examples:

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

dotagents list

dotagents list [--json]

Show declared skills and plugins with install/lock status. Use --json for machine-readable output. JSON output contains separate skills and plugins arrays.

Status output:

• ✓ means installed and present in the lockfile. JSON status: ok.
• ✗ means declared but not installed. JSON status: missing.
• ? means installed but not in the lockfile. JSON status: unlocked.

Source Formats

Format	Example	Description
GitHub	getsentry/skills	Auto-discovers skills by name
GitHub URL	https://github.com/getsentry/skills	Explicit GitHub source
GitHub SSH	git@github.com:getsentry/skills.git	GitHub over SSH
Pinned	getsentry/skills@v1.0.0	Locked to a specific ref
Git URL	git:https://git.corp.dev/repo	Non-GitHub git servers
GitLab URL	https://gitlab.com/group/repo	Explicit GitLab source
GitLab SSH	git@gitlab.com:group/repo.git	GitLab over SSH
Well-known HTTPS	https://cli.sentry.dev	HTTP source using .well-known skill discovery
Local	path:./my-skills/custom	Local directory, relative to the selected scope root

Configuration (agents.toml)

Top-level Fields

Field	Type	Default	Description
version	integer	–	Schema version. Always 1.
agents	string[]	[]	Agent targets: claude, cursor, codex, grok, vscode, opencode, pi. grok and pi are plugin-only targets.
subagents	table[]	[]	Custom subagent declarations for Claude, Cursor, Codex, and OpenCode
plugins	table[]	[]	Plugin declarations for Claude, Cursor, Codex, Grok, OpenCode, and Pi.
minimum_release_age	integer	–	Minimum commit age, in minutes, before a git skill, subagent, or plugin can install.
minimum_release_age_exclude	string[]	[]	Sources that bypass the minimum release age gate. Supports org names, org/repo, and org/*.
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 for URL servers, 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

Subagents

Field	Type	Required	Description
name	string	Yes	Lowercase subagent name to discover. Must match ^[a-z][a-z0-9-]*$.
source	string	Yes	Source repository or local directory. Supports GitHub/GitLab shorthands, git URLs, and path: sources; HTTPS well-known skill indexes are not supported for subagents.
ref	string	No	Optional git ref override.
path	string	No	Optional explicit subagent file path inside the source. Markdown paths are portable or native Markdown; .toml paths are Codex native artifacts.
targets	string[]	No	Optional subset of agent IDs. When absent or empty, defaults to every configured agent in agents; unsupported configured agents produce warnings.

dotagents treats subagents as best-effort portable dependencies, not a universal behavior schema. Runtime-specific behavior such as model routing, tool permissions, read-only modes, background execution, and reasoning effort stays in each tool’s native artifact.

dotagents discovers portable subagent Markdown from agents/ and .agents/agents/. It also imports native runtime artifacts from .claude/agents/*.md, .cursor/agents/*.md, .codex/agents/*.toml, and .opencode/agents/*.md. Root-level source files require an explicit path. Multiple portable matches for the same subagent are rejected as ambiguous, while matching native runtime artifacts are merged. When the source format matches a target runtime, dotagents reuses the native source content for that runtime and only adds its generated header marker. Other runtimes are generated from the portable name, description, and instructions.

Format	Source path	Matching output path	Required source fields
Portable Markdown	agents/*.md, .agents/agents/*.md	.agents/agents/<name>.md	YAML name, description; Markdown body
Claude Markdown	.claude/agents/*.md	.claude/agents/<name>.md	YAML name, description; Markdown body
Cursor Markdown	.cursor/agents/*.md	.cursor/agents/<name>.md	YAML description; Markdown body; name optional
Codex TOML	.codex/agents/*.toml	.codex/agents/<name>.toml	TOML name, description, developer_instructions
OpenCode Markdown	.opencode/agents/*.md	.opencode/agents/<name>.md	YAML description; Markdown body

Codex native name may use Codex-specific naming; dotagents uses the agents.toml name or filename as the portable ID when needed. Cursor native Markdown may omit name; dotagents uses the filename in that case. OpenCode native Markdown always uses the filename as the subagent name.

Generated files:

• Claude: .claude/agents/<name>.md
• Cursor: .cursor/agents/<name>.md
• Codex: .codex/agents/<name>.toml
• OpenCode: .opencode/agents/<name>.md

Generated files include a dotagents header marker. install and sync update managed files and do not overwrite hand-written files without the generated header marker. They also avoid creating duplicate runtime identities when an unmanaged file in the same agent directory already declares the same subagent. The deprecated --frozen flag does not change this behavior.

Plugins

[[plugins]] entries install canonical bundles into the selected scope’s managed plugin directory and generate runtime-specific outputs for configured agents. Plugin sources support GitHub/GitLab shorthands, git URLs, and path: sources; HTTPS well-known sources are not supported for plugins.

New plugin bundles follow Agent Plugins v1 with a required plugin.json and optional skills/ and mcp.json. dotagents preserves the raw bundle and generates isolated target adapters from the portable core. Generated JSON uses adjacent ownership sidecars; component symlinks use marker files in reserved .dotagents-managed/ directories. Client schemas receive no dotagents-only fields. Legacy generalized and native Claude/Cursor/Codex manifests remain supported during migration. Native imports preserve the owning manifest and expose only core metadata and Agent Skills to other clients; native components are never translated into unrelated clients’ formats.

Field	Type	Required	Description
name	string	Yes	Plugin identifier. Lowercase letters, numbers, hyphens, and dots.
source	string	Yes	Repository or local source.
ref	string	No	Optional git ref override.
path	string	No	Optional explicit plugin path inside the source.
targets	string[]	No	Optional subset of configured agents.

Generated plugin outputs include Claude/Cursor/Codex marketplaces and native manifests, Grok plugin directories, OpenCode skill links and portable MCP entries, and Pi skill links. OpenCode MCP keys use plugin.<plugin>.<server>; dotagents expands ${PLUGIN_ROOT} and ${PLUGIN_DATA} and preserves unrelated entries in the shared config. Generalized legacy bundles can also project Markdown agents into OpenCode; standard extension agents are preserved but not projected yet. dotagents rejects plugin sources that resolve to the same project’s .agents/plugins/<name>/ install destination. Global plugins use ~/.agents/plugins/<name>/ and global harness projections.

Scopes

Global Scope (default)

Operates on DOTAGENTS_HOME or ~/.agents/ in every directory. --global selects this scope explicitly; --user is a compatibility alias.

dotagents init
dotagents add getsentry/skills --all
dotagents add getsentry/agent-plugins review-tools
dotagents install

Global plugins install into ~/.agents/plugins/. Claude and Cursor marketplaces are generated below ~/.agents/, Codex uses ~/.agents/plugins/marketplace.json, Grok uses ~/.grok/plugins/, OpenCode skills use ~/.config/opencode/skills/ and plugin MCP entries use ~/.config/opencode/opencode.json, and Pi skills use ~/.agents/skills/.

Project Scope (--project)

Operates on the containing Git repository root, or the current directory outside Git. Commands other than init require agents.toml and never fall back globally.

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

Environment Variables

Variable	Description
DOTAGENTS_STATE_DIR	Override cache location. Default: ~/.local/dotagents.
DOTAGENTS_HOME	Override global-scope location. Default: ~/.agents.