Dotagents CLI

Overview

Use dotagents to manage prompt and skill assets without manually copying files between home repos and agent directories. Prefer deterministic, flag-driven commands so coding agents can run reliably in scripts and non-interactive environments.

Operating Workflow

1. •Confirm runtime and command availability.

• •Run dotagents --version.
• •If not installed globally, run via npx @artsnlabs/dotagents.

1. •Identify user intent.

• •Create new asset: use dotagents create.
• •Scaffold local project structure: use dotagents init.
• •Copy home asset into project/global target: use dotagents add.
• •Symlink home asset into project/global target: use dotagents link or dotagents add --mode symlink.
• •Modify an existing asset: use dotagents edit.
• •Validate home assets: use dotagents check.
• •Discover drift/conflicts between home and agent locations: use dotagents scan.
• •Configure home/agent paths: use dotagents config.
• •Sync registry-managed skills from home: use dotagents skill sync.
• •Pin project skills from manifest lockfiles: use dotagents skill lock, dotagents skill install, dotagents skill check-lock.

1. •Choose target scope before execution.

• •Home scope (default): no scope flags.
• •Project scope: -p.
• •Global agent homes: -g.
• •Specific agent: -a codex|claude|agents.
• •Combine -p with -a to target project-local agent folders like ./.codex.

1. •Prefer non-interactive command forms.

• •Supply names and flags explicitly.
• •Use batch-friendly flags (--all, --select, --json, --sync-all, --sync-select, --source-only, --strict).
• •Use interactive prompts only when the user explicitly wants guided selection.

1. •Verify results.

• •Check output paths printed by dotagents.
• •Re-run dotagents scan --json when validating sync state.

Agent Rules

• •Default to non-interactive execution for repeatability.
• •Keep --help output and command behavior aligned when advising users.
• •Do not assume one fixed home path; inspect with dotagents config --list when needed.
• •Surface actionable failures and retry guidance when flags are missing or targets are ambiguous.
• •Use --force only when overwrite is explicitly intended.
• •For CI or machine parsing, prefer JSON-capable flags (check --json, scan --json) and treat non-zero exits as gate failures.

Execution Defaults

Use these patterns in automation or scripted flows:

# Create a prompt in home with explicit content file
dotagents create prompt release --name release --content-file ./release.md

# Add a known skill to project-local .agents
dotagents add skill terminal-ui

# Add selected prompts to codex + claude global homes
dotagents add prompt --select release,triage -a codex,claude

# Add as symlink instead of copy
dotagents add prompt release --mode symlink

# Scaffold project .agents and seed starter assets
dotagents init -p --with prompt:release,skill:terminal-ui --link

# Dedicated link command for global agent target
dotagents link skill terminal-ui -a codex

# Edit a skill helper file in project codex scope
dotagents edit skill terminal-ui -p -a codex --file references/checklist.md --editor "code --wait"

# Review drift before syncing
dotagents scan --source ./.tmp/sourceA --source-only --diff

# Scan and sync specific unsynced assets
dotagents scan --sync-select prompt:release:/abs/path/release.md

# Validate only skills and fail on warnings
dotagents check skill --strict --json

# Resolve and install pinned project skills
dotagents skill lock
dotagents skill install
dotagents skill check-lock

References

• •Command Surface
• •Agent Execution Checklist
• •Troubleshooting