CLI Reference: ralph_import.sh
Relevant source files
The following files were used as context for generating this wiki page:
The ralph_import.sh script is a command-line tool designed to convert existing Product Requirements Documents (PRDs) or other specification files into the structured format required by the Ralph autonomous development system. It leverages the Claude Code CLI to intelligently analyze the source document and generate the necessary control files, including PROMPT.md, @fix_plan.md, and specs/requirements.md. This process bootstraps a new Ralph project, making existing specifications actionable for autonomous development.
The script is installed as a global command ralph-import by the main install.sh script, making it accessible from any directory. It supports modern Claude Code CLI features like JSON output for more reliable parsing and error handling, while maintaining backward compatibility with older CLI versions.
Sources: ralph_import.sh:2-4, 335-340, README.md:121-123, 139-155, install.sh:120-129
Usage and Arguments
The script is executed from the command line, taking a source file as a mandatory argument and an optional project name.
Sources: ralph_import.sh:265-271
# Example usage
ralph-import <source-file> [project-name]
# Convert a markdown PRD and name the project 'my-app'
ralph-import product-requirements.md my-app
# Convert a text file and let Ralph auto-name the project
ralph-import requirements.txt
Sources: README.md:158-167, ralph_import.sh:268-271
Arguments
| Argument | Description | Required | Default |
|---|---|---|---|
source-file | Path to the PRD or specification file. Supports formats like .md, .txt, .json, .docx, and .pdf. | Yes | N/A |
project-name | The name for the new Ralph project directory. | No | The base name of the source-file without its extension. |
Sources: ralph_import.sh:265-271, 281-283
Core Workflow
The script follows a sequence of steps to set up a new project and convert the provided PRD.
This diagram illustrates the high-level execution flow of the ralph_import.sh script.
Sources: ralph_import.sh:285-333
1. Initialization and Validation
The main function first validates that a source-file argument is provided and that the file exists. If no project-name is given, it derives one from the source filename. It then runs check_dependencies to ensure ralph-setup is installed.
Sources: ralph_import.sh:274-284, 287
2. Project Setup
The script calls ralph-setup "$project_name" to create the standard Ralph project directory structure. It then changes into the new project directory and copies the source PRD file into it.
Sources: ralph_import.sh:289-295
3. PRD Conversion
The core logic resides in the convert_prd function.
- Prompt Generation: A detailed prompt is constructed in a temporary file (
.ralph_conversion_prompt.md). This prompt instructs Claude to analyze the source PRD and generate three specific output files:PROMPT.md,@fix_plan.md, andspecs/requirements.md. The content of the user's source PRD is appended to this prompt. - Claude Execution: The script executes the Claude Code CLI, piping the generated prompt as input. It intelligently decides whether to use modern CLI features based on the detected version of the Claude tool.
- Response Handling: The output from Claude is captured in
.ralph_conversion_output.json. The script then parses this output to determine the result of the conversion. - File Verification: After the conversion, the script checks for the existence of the expected output files and reports which were created and which might be missing.
- Cleanup: Temporary files used during the process are removed.
Sources: ralph_import.sh:300-302, 305-333
This sequence diagram shows the interactions between the user, the script, and external tools.
Sources: ralph_import.sh:289-333
Modern CLI Integration
A key feature of ralph_import.sh is its support for modern Claude Code CLI features, which enables more robust and reliable conversions. This is enabled if the CLI version is at or above 2.0.76.
Sources: ralph_import.sh:11, 203-205, CLAUDE.md:15-19
Version Check
The check_claude_version function determines if the installed Claude Code CLI meets the minimum version requirement. It performs a numeric semantic version comparison. If the version is sufficient, the script proceeds in modern mode; otherwise, it falls back to standard mode.
Sources: ralph_import.sh:158-200
Modern Execution
When modern mode is active, the script invokes the Claude Code CLI with specific flags for structured interaction.
$CLAUDE_CODE_CMD --output-format "$CLAUDE_OUTPUT_FORMAT" --allowedTools "${CLAUDE_ALLOWED_TOOLS[@]}" < "$CONVERSION_PROMPT_FILE" > "$CONVERSION_OUTPUT_FILE" 2> "$stderr_file"
Sources: ralph_import.sh:421-423
| Flag/Variable | Value | Purpose |
|---|---|---|
CLAUDE_OUTPUT_FORMAT | json | Instructs the CLI to return a structured JSON response instead of plain text. |
CLAUDE_ALLOWED_TOOLS | ('Read' 'Write' 'Bash(mkdir:*)' 'Bash(cp:*)') | A bash array of tool permissions. This allows Claude to perform file operations like creating the output files without requiring interactive user prompts. |
CLAUDE_MIN_VERSION | 2.0.76 | The minimum version required for these features. |
Sources: ralph_import.sh:9-11, 421-423, README.md:172-178
Response Parsing
The script can handle both JSON and plain text responses from the Claude CLI.
Format Detection
The detect_response_format function inspects the output file to determine its format. It checks if the file is non-empty, starts with { or [, and validates as JSON using jq. If any of these checks fail, it defaults to "text".
Sources: ralph_import.sh:66-91
JSON Parsing
If the response is identified as JSON, the parse_conversion_response function is called. It uses jq to extract detailed information from the structured response and populates a set of global variables. This allows for more precise status reporting and error handling.
Sources: ralph_import.sh:93-156
The following global variables are set by parse_conversion_response:
| Variable | jq Filter | Description |
|---|---|---|
PARSED_RESULT | .result // .summary // "" | The summary text of the conversion result. |
PARSED_SESSION_ID | .sessionId // .session_id // "" | The session ID for potential continuation. |
PARSED_FILES_CHANGED | .metadata.files_changed // .files_changed // 0 | The number of files modified by Claude. |
PARSED_HAS_ERRORS | .metadata.has_errors // .has_errors // false | A boolean flag indicating if errors occurred. |
PARSED_COMPLETION_STATUS | .metadata.completion_status // .completion_status // "unknown" | The status of the conversion (complete, partial, failed). |
PARSED_ERROR_MESSAGE | .metadata.error_message // .error_message // "" | A specific error message if the conversion failed. |
PARSED_ERROR_CODE | .metadata.error_code // .error_code // "" | A specific error code if the conversion failed. |
PARSED_FILES_CREATED | .metadata.files_created // [] | @json | A JSON array of files that Claude reported creating. |
PARSED_MISSING_FILES | .metadata.missing_files // [] | @json | A JSON array of files that Claude reported were missing. |
Sources: ralph_import.sh:12-21, 126-153
Generated Files
The primary goal of the conversion process is to generate three key files that structure the new Ralph project. The instructions for creating these files are embedded within the conversion prompt.
Sources: ralph_import.sh:322-386, README.md:169-171
| Filename | Purpose |
|---|---|
PROMPT.md | Contains the main development instructions for Ralph. It transforms the high-level goals from the PRD into a format the autonomous agent can follow, including objectives, principles, and requirements. |
@fix_plan.md | A prioritized task list. The script instructs Claude to break down the PRD requirements into actionable, checkable tasks categorized by priority (High, Medium, Low). |
specs/requirements.md | A detailed technical specification document. This file is meant to preserve all technical details from the original PRD, such as architecture, data models, and API specifications. |
Sources: ralph_import.sh:325-386, create_files.sh:220-278
Installation
The ralph_import.sh script is made globally available as ralph-import by the main install.sh script. The installer creates a wrapper script in $HOME/.local/bin/ that executes the actual ralph_import.sh file, which is stored in $HOME/.ralph/.
Sources: install.sh:120-129, 140-143
Conclusion
ralph_import.sh is a crucial utility in the Ralph ecosystem, acting as the bridge between human-written specifications and an AI-ready project structure. By automating the conversion of PRDs, it significantly accelerates the setup of new autonomous development projects. Its integration with modern Claude Code CLI features like JSON output and controlled tool usage demonstrates a sophisticated approach to reliable human-AI interaction, complete with structured data exchange and robust error handling.