CLI Reference

Every dot command at a glance — install, create, publish, and discover.

The dot CLI is the fastest way to work with DOT from a terminal. Use it to initialize a workspace, install assets, create your own, search the registry, and publish to your namespace.

Quick Reference:

Command	What It Does
dot init	Create a workspace
dot init dance	Scaffold a new SKILL.md directory
dot add <owner/repo>	Add a Dance skill from GitHub
dot install <urn>	Install an asset from the registry
dot create	Generate a local asset template
dot publish	Publish to registry
dot search	Search registry
dot list	List registry packages
dot check	Check Dance skills for updates
dot update	Update Dance skills to latest
dot login	Authenticate via GitHub
dot logout	Remove saved credentials

dot init#

Create a .dance-of-tal/ workspace. Use once per project.

dot init

Creates:

.dance-of-tal/
├── assets/            ← Installed & created assets
│   ├── tal/
│   ├── dance/
│   ├── performer/
│   └── act/
└── drafts/            ← Work-in-progress
    ├── tal/
    ├── dance/
    ├── performer/
    └── act/

dot init dance#

Scaffold a new Dance skill directory with a SKILL.md template.

dot init dance --name my-skill

Creates:

my-skill/
├── SKILL.md           ← Edit this to define your skill
├── scripts/           ← Executable helpers
└── references/        ← Reference documents

Once you've edited the SKILL.md, push the repo to GitHub and run dot add to install it.

dot add <owner>/<repo>#

Pull a Dance skill directly from a GitHub repository.

dot add monarchjuno/sprint-reviewer

Installs the SKILL.md and associated files into your local .dance-of-tal/assets directory. It securely packages the remote prompts and tools.

Shorthand with skill filter#

dot add owner/repo@skill-name

The @skill suffix filters to a specific skill by name — equivalent to --skill <name>.

Options#

dot install <urn>#

Install an asset from the public registry by URN.

dot install tal/@acme/agent-presets/system-architect
dot install dance/@acme/agent-presets/pr-review-standard
dot install performer/@acme/agent-presets/sprint
dot install act/@acme/agent-presets/incident-response

Cascading install behavior#

Tip: You rarely need to install Tal/Dance individually. Installing a Performer or Act brings everything you need.

Global install option#

dot install performer/@acme/agent-presets/sprint --global

Installs to DOT home instead of the current project. Use project-local by default.

dot create#

Generate a local template for a new asset.

dot create --kind tal --stage agent-presets --name my-persona
dot create --kind performer --stage agent-presets --name sprint
dot create --kind act --stage workflows --name incident-response

Note: dot create --kind dance is not supported. Dance assets use the SKILL.md format — use dot init dance --name my-skill instead.

Options#

Generated assets save to:

.dance-of-tal/assets/<kind>/@<author>/<stage>/<name>.json

Typical flow#

dot init
dot create --kind tal --stage agent-presets --name my-persona
# Edit the generated file...
dot publish --kind tal --stage agent-presets --name my-persona

dot publish#

Publish a local asset to the registry.

dot publish --kind tal --stage agent-presets --name my-persona --tags "backend,correctness"

Note: Dance assets cannot be published directly. Dance uses the SKILL.md format from GitHub repos. Use dot add <owner/repo> to install and auto-register instead.

Required options#

What happens#

1. DOT checks you're logged in
2. Asks you to confirm Terms of Service
3. Validates asset schema (canonical contract)
4. Resolves dependencies (for performer/act)
5. Publishes to the registry

Important: If your dependency belongs to another author and isn't already published, the publish will stop and tell you why.

→ See Publishing Assets for the full flow.

dot search#

Search the public registry by keyword.

dot search reviewer
dot search security --kind dance
dot search incident --kind act --tag workflow

Searches across URN, author, description, and tags.

Options#

dot list#

List registry packages.

dot list
dot list --kind performer
dot list --mine
dot list --stage agent-presets

dot check#

Check installed Dance skills for available updates by comparing local file hashes against their remote GitHub sources.

dot check

If updates are available, run dot update to apply them.

dot update#

Update installed Dance skills to the latest version from their GitHub sources.

dot update
dot update --force

dot login#

Authenticate with GitHub so you can publish under your namespace.

dot login

What happens:

1. Opens GitHub OAuth via Supabase in your browser
2. Waits for authorization (timeout: 3 min)
3. Token saves to ~/.dance-of-tal/auth.json

Your GitHub username becomes your protected DOT namespace.

dot logout#

Remove saved credentials.

dot logout

URN Format#

Every installable DOT asset uses:

<kind>/@<author>/<stage>/<name>

Examples:

Workspace Layout Reference#

Project root/
└── .dance-of-tal/
    ├── assets/
    │   ├── tal/@author/<stage>/<name>.json
    │   ├── dance/@author/<stage>/<name>/
    │   ├── performer/@author/<stage>/<name>.json
    │   └── act/@author/<stage>/<name>.json
    └── drafts/
        ├── tal/
        ├── dance/
        ├── performer/
        └── act/

Home directory/
└── ~/.dance-of-tal/
    └── auth.json

Recommended First Commands#

Just want to get productive#

dot init
dot install performer/@your-team/agent-presets/default-engineer

Want to publish your own asset#

dot login
dot create --kind tal --stage my-project --name my-persona
# Edit the file...
dot publish --kind tal --stage my-project --name my-persona

Want to add a Dance skill from GitHub#

dot init
dot add monarchjuno/sprint-reviewer
dot check