CLI tool for Ralph-dev - efficient operations for AI agents
npm install ralph-devTypeScript command-line tool for Ralph-dev state and task management.
The Ralph-dev CLI provides efficient operations for managing development workflow state, tasks, and language detection. It's designed to be called from Ralph-dev skills during autonomous development phases.
Key capabilities:
- State management across 5 workflow phases
- Task CRUD operations with dependency tracking
- Automatic language and framework detection
- JSON output for integration with bash scripts
``bash`
cd cli
npm install
npm run build
The CLI binary is located at cli/bin/ralph-dev.js and can be invoked via:`bash`
./bin/ralph-dev.js or after build
npx ralph-dev
Manage workflow state stored in .ralph-dev/state.json.
Get current state:
`bash`
ralph-dev state get [--json]
Set state:
`bash`
ralph-dev state set --phase Example:
ralph-dev state set --phase implement --task auth.login.ui
Update state fields:
`bash`
ralph-dev state update [--phase Example:
ralph-dev state update --phase heal
ralph-dev state update --task auth.signup.api
Clear state:
`bash`
ralph-dev state clear
Supported phases:
- clarify - Requirements clarificationbreakdown
- - Task decompositionimplement
- - Implementation loopheal
- - Error recoverydeliver
- - Quality gates and PR creation
Manage tasks in .ralph-dev/tasks/ directory.
Initialize task system:
`bash`
ralph-dev tasks init [--project-goal Example:
ralph-dev tasks init --project-goal "User authentication system" --language typescript --framework nextjs
Create a task:
`bashShorthand syntax (positional argument):
ralph-dev tasks create
--module
--description
[--priority <1-10>] \
[--estimated-minutes
[--criteria
[--dependencies
[--test-pattern
List tasks:
`bash
ralph-dev tasks list [--status ] [--json]
Examples:
ralph-dev tasks list --status pending
ralph-dev tasks list --json
`Get next task (with comprehensive context):
`bash
ralph-dev tasks next [--json]
`This command returns the highest-priority pending task with:
- Current directory and git information
- Workflow state and phase
- Progress statistics (completed/failed/pending)
- Recent activity from progress.log
- Dependency status
- Test requirements
Get specific task:
`bash
ralph-dev tasks get [--json]
Example:
ralph-dev tasks get auth.login.ui
`Mark task as in progress:
`bash
ralph-dev tasks start
Example:
ralph-dev tasks start auth.login.ui
`Mark task as completed:
`bash
ralph-dev tasks done [--duration ]
Example:
ralph-dev tasks done auth.login.ui --duration "23m 15s"
`Mark task as failed:
`bash
ralph-dev tasks fail --reason
Example:
ralph-dev tasks fail auth.login.ui --reason "Missing dependencies: react-hook-form"
`$3
Detect project language and framework.
Detect language:
`bash
ralph-dev detect [--json]
`Returns detected language configuration including:
- Primary language
- Framework (if applicable)
- Test framework
- Build tool
- Verification commands (type-check, lint, test, build)
AI-powered detection:
`bash
ralph-dev detect-ai [--json]
`Uses AI agent to analyze project structure for more accurate detection.
Usage in Skills
The CLI is designed to be called from bash skills. Here's a typical workflow:
`bash
Phase 3: Implementation loop
while true; do
# Get next task
TASK_JSON=$(ralph-dev tasks next --json) if echo "$TASK_JSON" | jq -e '.error' > /dev/null; then
echo "No more tasks"
break
fi
TASK_ID=$(echo "$TASK_JSON" | jq -r '.task.id')
# Mark as in progress
ralph-dev tasks start "$TASK_ID"
# Update workflow state
ralph-dev state update --task "$TASK_ID"
# Implement task (spawn agent, run tests, etc.)
# ... implementation logic ...
if [ $? -eq 0 ]; then
# Mark as completed
ralph-dev tasks done "$TASK_ID"
else
# Mark as failed
ralph-dev tasks fail "$TASK_ID" --reason "Tests failed"
# Trigger Phase 4: HEAL
break
fi
done
`Data Structures
$3
`json
{
"phase": "implement",
"currentTask": "auth.login.ui",
"prd": {},
"errors": [],
"startedAt": "2026-01-19T10:00:00Z",
"updatedAt": "2026-01-19T10:15:00Z"
}
`$3
`markdown
---
id: auth.login.ui
module: auth
priority: 2
status: in_progress
estimatedMinutes: 25
dependencies:
- setup.scaffold
testRequirements:
unit:
required: true
pattern: "*/.test.ts"
---Login UI Component
Acceptance Criteria
1. Form displays email and password fields
2. Submit button validates email format
3. Error messages display on validation failureNotes
Using React Hook Form for validation.
`$3
`json
{
"metadata": {
"projectGoal": "User authentication system",
"languageConfig": {
"language": "typescript",
"framework": "nextjs"
}
},
"tasks": {
"auth.login.ui": {
"module": "auth",
"priority": 2,
"status": "in_progress",
"filePath": "auth/login.ui.md"
}
}
}
`Architecture
Ralph-dev CLI uses a layered architecture with clear separation of concerns:
`
┌─────────────────────────────────────────┐
│ Commands (CLI Interface) │ ← Thin layer: parse args, format output
├─────────────────────────────────────────┤
│ Services (Business Logic) │ ← Core logic: task management, state, healing
├─────────────────────────────────────────┤
│ Repositories (Data Access) │ ← Abstract persistence: tasks, state
├─────────────────────────────────────────┤
│ Domain Models (Entities) │ ← Rich entities with behavior
├─────────────────────────────────────────┤
│ Infrastructure (File System, Logger) │ ← Technical services with retry logic
└─────────────────────────────────────────┘
`Key architectural features:
- Dependency Injection: Services and repositories are injected via constructors for testability
- Repository Pattern: All data access abstracted behind interfaces
- Rich Domain Models: Entities enforce business rules and state transitions
- Circuit Breaker: Prevents cascade failures in healing phase (auto-stops after 5 failures)
- Saga Pattern: Ensures atomic multi-step operations with automatic rollback
See CLAUDE.md for detailed architecture documentation, design patterns, and development guidelines.
Development
Run in watch mode:
`bash
npm run dev
`Run tests:
`bash
npm test
`Lint code:
`bash
npm run lint
`Format code:
`bash
npm run format
`Build for production:
`bash
npm run build
`Requirements
- Node.js >= 18.0.0
- npm >= 9.0.0
Dependencies
Runtime:
-
commander - CLI framework
- chalk - Terminal colors
- yaml - YAML parsing
- fs-extra - Enhanced file system operations
- zod - Schema validationDevelopment:
-
typescript - Type safety
- vitest - Testing framework
- eslint - Code linting
- prettier - Code formattingIntegration with Ralph-dev
This CLI is bootstrapped automatically by
shared/bootstrap-cli.sh when Ralph-dev skills are invoked. The bootstrap script:
1. Checks if CLI binary exists
2. Builds CLI on first use (npm install + tsc)
3. Exports ralph-dev` function for use in skillsMIT - Part of the Ralph-dev project
---
Version: 0.4.3
Status: Active development
Repository: https://github.com/mylukin/ralph-dev