🔧 VERSA CLI

Reference Command-Line Tool for the .ai/ Folder Standard

Documentation · VERSA Spec · Examples

---

🚀 What is versa CLI?

The official command-line tool for working with VERSA .ai/ folders. Initialize, validate, merge profiles, and generate agent context with a single command.

# Initialize a new .ai/ folder
versa init

# Validate your configuration
versa lint

# Print merged configuration
versa print --profile cursor

# Generate agent context
versa context --agent code-reviewer

---

✨ Features

• 🎯 Scaffold - Create .ai/ folders with sensible defaults
• ✅ Validate - Lint JSON and Markdown against VERSA schemas
• 🔄 Merge - Deep-merge profiles with base configuration
• 📦 Context - Assemble complete agent payloads
• 🧾 Export - Print merged configs in JSON/YAML/Text

---

📦 Installation

# npm
npm install -g @dotaislash/cli

# yarn
yarn global add @dotaislash/cli

# pnpm
pnpm add -g @dotaislash/cli

# Or use npx (no install)
npx @dotaislash/cli init

---

🎯 Commands

versa init

Scaffold a new .ai/ folder in your project.

# Interactive setup
versa init

# With options
versa init --minimal              # Minimal setup
versa init --template typescript  # Template support (planned)
versa init --profile cursor       # Include profile

Creates:

.ai/
├── context.json          # Base configuration
├── profiles/             # Tool-specific overrides
├── rules/                # Markdown rules
│   └── style.md
├── agents/               # Agent configurations
└── tools/                # MCP server configs

---

versa lint

Validate your .ai/ folder against VERSA schemas.

# Lint entire .ai/ folder
versa lint

# Lint specific file
versa lint .ai/context.json

# Strict mode (fail on warnings)
versa lint --strict

Checks:

• ✅ JSON schema validation (context, profiles, agents, tools, knowledge, memory)
• ✅ Markdown ai:meta front matter for rules and prompts
• ✅ File references exist
• ✅ Circular dependency detection for agent references

---

versa print

Print merged configuration for a specific profile.

# Print base configuration
versa print

# Print with profile merged
versa print --profile cursor

# Output to file
versa print --profile windsurf > windsurf-config.json

# Pretty print
versa print --pretty

# Show merge details
versa print --profile cursor --show-merges

---

versa context

Assemble complete context payload for an agent.

# Generate context for an agent
versa context --agent code-reviewer

# With specific profile
versa context --agent code-reviewer --profile cursor

# Output formats
versa context --agent code-reviewer --format json
versa context --agent code-reviewer --format yaml

---

📖 Usage Examples

Initialize a New Project

cd my-project
versa init

# Or minimal scaffold
versa init --minimal

Validate Before Commit

# Add to your CI pipeline
npm run lint && versa lint

Generate Context for Multiple Tools

# Cursor
versa context --profile cursor > .cursor-context.json

# Windsurf
versa context --profile windsurf > .windsurf-context.json

# Claude
versa context --profile claude > .claude-context.json

Planned Features

• versa diff
• versa preview
• versa import
• versa templates
• versa watch
• versa lint --fix
• Template scaffolds for versa init --template

---

🛠️ Development

# Clone repository
git clone https://github.com/dotAIslash/dotaislash-cli.git
cd dotaislash-cli

# Install dependencies
pnpm install

# Run in development
pnpm dev

# Build
pnpm build

# Run tests
pnpm test

# Lint code
pnpm lint

---

📚 Documentation

• 📖 CLI Reference
• 🎯 Command Guide
• 🧩 API Documentation
• 📝 Configuration Options
• 🎨 Template Guide

---

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Ways to Help

• 🐛 Report bugs and issues
• 💡 Suggest new commands or features
• 📝 Improve documentation
• 🧪 Add tests
• 🎨 Create templates

---

📄 License

MIT © dotAIslash

---

Part of the VERSA ecosystem

Spec · Schemas · Examples · Adapters

⭐ Star us on GitHub