@paths.design/caws-cli
Advanced tools
CAWS CLI - Coding Agent Workflow System command-line tools for spec management, quality gates, and AI-assisted development
Command Line Interface for CAWS (Coding Agent Workflow System)
The CAWS CLI is the primary interface for developers and agents to interact with CAWS quality assurance and workflow management capabilities. It provides comprehensive project scaffolding, validation, and management tools.
The CAWS CLI serves as the central control point for:
npm install -g @paths.design/caws-cli
# Clone the CAWS monorepo
git clone https://github.com/paths-design/caws.git
cd caws
# Install dependencies
npm install
# Build all packages
npm run build
# Use locally
node packages/caws-cli/dist/index.js --help
# Initialize a new CAWS project
caws init my-project
# Add CAWS to existing project
caws scaffold
# Validate working specification
caws validate
# Get help
caws --help
# Evaluate work quality (JSON output for agents)
caws agent evaluate .caws/working-spec.yaml
# Get iterative development guidance
caws agent iterate --current-state "Started implementation" .caws/working-spec.yaml
# Create a waiver for exceptional circumstances
caws waivers create \
--title "Emergency security fix" \
--reason emergency_hotfix \
--gates coverage_threshold \
--expires-at "2025-11-01T00:00:00Z" \
--approved-by "security-team"
# List active waivers
caws waivers list
# Revoke a waiver
caws waivers revoke WV-0001
# Analyze project for CI/CD optimizations
caws cicd analyze
# Generate optimized GitHub Actions workflow
caws cicd generate github --output .github/workflows/caws-gates.yml
# Smart test selection based on changes
caws cicd test-selection --from-commit HEAD~1
# Dry-run validation without side effects
caws experimental --dry-run validate .caws/working-spec.yaml
# Experimental quality gates
caws experimental quality-gates .caws/working-spec.yaml --parallel-execution
# List available CAWS tools
caws tools list
# Execute specific tool
caws tools run validate
# Manage tool configurations
caws tools --help
The CLI is built with a modular architecture:
caws-cli/
├── src/
│ ├── index.js # Main CLI entry point
│ ├── waivers-manager.js # Waiver system implementation
│ ├── cicd-optimizer.js # CI/CD optimization logic
│ └── tool-loader.js # Dynamic tool loading system
├── templates/ # Project templates
└── dist/ # Compiled output
┌─────────────────┐ ┌──────────────────┐
│ caws-cli │────│ caws-template │
│ (Commands) │ │ (Tools & Config)│
└─────────────────┘ └──────────────────┘
│ │
└───────────────────────┘
│
┌─────────────────┐
│ caws-mcp-server │
│ (Agent Bridge) │
└─────────────────┘
The CLI automatically executes quality gates defined in the template:
The CLI provides structured APIs for agents:
// Agent can evaluate work quality
const result = await runCommand('caws agent evaluate spec.yaml');
// Returns: { success: true, evaluation: { quality_score: 0.85, ... } }
// Agent can get guidance for next steps
const guidance = await runCommand('caws agent iterate --current-state "..." spec.yaml');
// Returns: { guidance: "...", next_steps: [...], confidence: 0.8 }
Projects use .caws/working-spec.yaml files:
id: PROJ-001
title: 'Feature implementation'
risk_tier: 2
mode: feature
change_budget:
max_files: 25
max_loc: 1000
acceptance:
- id: 'A1'
given: 'Current state'
when: 'Feature implemented'
then: 'Expected behavior'
Tools are configured in apps/tools/caws/ directory with metadata:
// Tool metadata
{
id: 'validate',
name: 'Working Spec Validator',
capabilities: ['validation', 'quality-gates'],
version: '1.0.0'
}
cd packages/caws-cli
npm run build # Compile TypeScript
npm run dev # Development with watch
npm run lint # Run ESLint
npm run test # Run tests
src/index.jsTools follow a standardized interface:
class MyTool extends BaseTool {
getMetadata() {
return {
id: 'my-tool',
name: 'My Custom Tool',
capabilities: ['validation'],
version: '1.0.0',
};
}
async executeImpl(parameters, context) {
// Tool logic here
return { success: true, output: result };
}
}
npm run test # All tests
npm run test:unit # Unit tests only
npm run test:integration # Integration tests
npm run test:contract # Contract tests
Command not found
# Ensure global installation
npm install -g @paths.design/caws-cli
caws --version
# Or use local installation
node packages/caws-cli/dist/index.js --help
Tool loading errors
# Check tool directory structure
ls -la apps/tools/caws/
# Validate tool metadata
caws tools list
# Check tool permissions
chmod +x apps/tools/caws/*.js
Validation failures
# Check working spec syntax
caws validate --suggestions .caws/working-spec.yaml
# Auto-fix common issues
caws validate --auto-fix .caws/working-spec.yaml
MIT License - see main project LICENSE file.
FAQs
CAWS CLI - Coding Agent Workflow System command-line tools for spec management, quality gates, and AI-assisted development
We found that @paths.design/caws-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
A supply chain attack on Axios introduced a malicious dependency, plain-crypto-js@4.2.1, published minutes earlier and absent from the project’s GitHub releases.
Research
Malicious versions of the Telnyx Python SDK on PyPI delivered credential-stealing malware via a multi-stage supply chain attack.
Security News
TeamPCP is partnering with ransomware group Vect to turn open source supply chain attacks on tools like Trivy and LiteLLM into large-scale ransomware operations.