Skip to content

cli-reference.md

Latest commit

 

History

History
179 lines (126 loc) · 3.38 KB

cli-reference.md

File metadata and controls

179 lines (126 loc) · 3.38 KB

CLI Reference

Commands

mai use <tool>

Switch active AI tool.

mai use claude

Tools: claude, cursor, windsurf, qwen

mai install <pack>[@version]

Install a pack.

# Local installation (default, stored in .mai/)
mai install my-pack
mai install my-pack@1.2.3

# Global installation (user-wide, stored in XDG dirs)
mai install -g my-pack
mai install --global my-pack

# With metadata
mai install my-pack --description "Desc" --source "https://..."

Options:

  • -g, --global — Install globally (user-wide) instead of locally (project-specific)
  • --description <DESC> — Pack description
  • --source <URL> — Pack source URL

Version formats: latest, 1.2.3, ^1.2.3, ~1.2.3, >=1.0.0, <2.0.0

Pack formats:

  • name — Default type (skill)
  • type/name — Explicit type (skill/, command/, mcp/)
  • name@version — With version
  • type/name@version — Full format

mai list

List installed packs.

# List packs for active tool
mai list

# List packs for specific tool
mai list --tool claude

# List all packs (all tools)
mai list --all

# List only global packs
mai list --global

# List only local packs
mai list --local

Options:

  • -t, --tool <TOOL> — Filter by tool name
  • -a, --all — List all tools
  • --global — List only global packs
  • --local — List only local packs

Output format: [scope] name version (type) - description

mai remove <pack>

Remove a pack.

# Remove local pack (default)
mai remove my-pack

# Remove global pack
mai remove -g my-pack
mai remove --global my-pack

Options:

  • -g, --global — Remove from global installation
  • -t, --tool <TOOL> — Tool to remove from (uses active tool if not specified)

mai update <pack>

Update a pack.

# Update local pack
mai update my-pack
mai update my-pack@2.0.0

# Update global pack
mai update -g my-pack
mai update --global --latest my-pack

Options:

  • -g, --global — Update global installation
  • -t, --tool <TOOL> — Tool to update for
  • --latest — Update to latest version

mai init

Initialize a new mai project. Creates mai.toml in current directory.

mai init

Creates: mai.toml (project manifest)

mai sync

Sync project packs with global registry. Generates mai.lock.

mai sync

Requires: mai.toml Creates: mai.lock (pinned versions + hashes)

mai check

Verify lock file integrity. Checks all locked packs exist and hashes match.

mai check

Requires: mai.lock Exit codes: 0 (valid), 1 (integrity failure)

mai completions <shell>

Generate shell completions.

mai completions bash > ~/.local/share/bash-completion/completions/mai
mai completions zsh > ~/.zfunc/_mai
mai completions fish > ~/.config/fish/completions/mai.fish

Shells: bash, zsh, fish

Installation Scopes

mai supports two installation scopes:

Local (Default)

  • Stored in: .mai/ (project root)
  • Use for: Project-specific dependencies
  • Priority: Checked first during resolution

Global

  • Stored in: XDG directories or ~/.mai/ fallback
  • Use for: User-wide tools, common skills
  • Priority: Checked after local

Pack Types

  • skill — AI agent skills and capabilities
  • command — CLI tools for AI assistants
  • mcp — Model Context Protocol connectors