CLI reference
Complete reference for all SCRIBE CLI commands.
Global options
| Option |
Description |
--help |
Show help and exit |
cases validate
Validate case study files against the LinkML schema.
Synopsis
ai4c-scribe cases validate DIR
Arguments
| Argument |
Required |
Description |
DIR |
Yes |
Directory containing case study .md files |
Examples
# Validate all case studies in a directory
ai4c-scribe cases validate cases/go-ontology/
# Validate a different set
ai4c-scribe cases validate cases/mondo/
Output
Reports validation results for each file:
Validating cases/go-ontology/...
31158.md: OK
31200.md: OK
31305.md: ERROR - missing required field 'task_type'
2/3 valid, 1 error(s)
What is validated
- All required fields present (
repo, issue_number, pr_number, issue_title, pr_author, task_type, difficulty, scope)
- Enum values match allowed values
- Date fields are valid ISO 8601 format
repo matches owner/repo pattern
- Numeric fields are positive integers
cases list
List case studies with summary metadata.
Synopsis
ai4c-scribe cases list DIR
Arguments
| Argument |
Required |
Description |
DIR |
Yes |
Directory containing case study .md files |
Examples
# List all case studies
ai4c-scribe cases list cases/go-ontology/
# Pipe to other tools
ai4c-scribe cases list cases/go-ontology/ | grep "complex"
Output
Displays a summary table of case studies:
PR# Issue# Task Type Difficulty Scope Review Outcome
31158 31100 new_term simple single_term changes_requested
31200 31150 reclassify moderate few_terms approved
31305 31290 fix_logic complex multi_file changes_requested
fix-issue
Run an AI agent to fix a GitHub issue in a local worktree.
Synopsis
ai4c-scribe fix-issue REPO ISSUE -w WORK_DIR [OPTIONS]
Arguments
| Argument |
Required |
Description |
REPO |
Yes |
Repository in owner/repo format |
ISSUE |
Yes |
Issue number to fix |
Options
| Option |
Short |
Default |
Description |
--work-dir |
-w |
Required |
Path to git worktree |
--config |
-c |
.ai4cscribe/runner.yaml |
Config file path |
--system-prompt |
-s |
None |
Override system prompt |
--prompt-file |
-f |
None |
System prompt file |
--overlay |
-o |
None |
Overlay directory |
--dry-run |
|
False |
Setup only, don't run agent |
--force |
-y |
False |
Skip confirmation prompt |
Examples
# Basic usage
ai4c-scribe fix-issue monarch-initiative/mondo 7712 -w /path/to/worktree
# Dry run (setup only)
ai4c-scribe fix-issue monarch-initiative/mondo 7712 -w /path/to/worktree --dry-run
# Skip confirmation
ai4c-scribe fix-issue monarch-initiative/mondo 7712 -w /path/to/worktree --force
Configuration file
Create .ai4cscribe/runner.yaml in your worktree:
experiment_id: exp001
system_prompt: |
You are an expert developer. Analyze the issue and
implement a clean solution following existing patterns.
agent_timeout: 600
Output
- Creates branch
{experiment_id}-issue-{N} in worktree
- Resets worktree to PR base commit (if linked PR exists)
- Runs agent with issue context
- Agent commits changes to branch
Compare two diffs and compute similarity metrics.
Synopsis
ai4c-scribe metadiff ACTION [OPTIONS]
Actions
| Action |
Description |
compare |
Compare two diff files |
configs |
List available comparison configs |
Compare options
| Option |
Short |
Default |
Description |
--config |
-c |
None |
Comparison config (e.g., obo) |
--output |
-o |
None |
Output file path |
--format |
-f |
text |
Output format: text or json |
Examples
# List available configs
ai4c-scribe metadiff configs
# Compare two diffs
ai4c-scribe metadiff compare human.diff agent.diff
# With OBO ontology config
ai4c-scribe metadiff compare human.diff agent.diff -c obo
# Output as JSON
ai4c-scribe metadiff compare human.diff agent.diff -o results.json -f json
Metrics
| Metric |
Description |
similarity |
Jaccard similarity of changed lines (0-1) |
precision |
True positives / predicted changes (0-1) |
recall |
True positives / actual changes (0-1) |
f1_score |
Harmonic mean of precision and recall (0-1) |
Configs
The obo config is optimized for OBO ontology diffs:
- Masks auto-generated IDs
- Ignores metadata lines
- Normalizes whitespace
Exit codes
| Code |
Meaning |
| 0 |
Success |
| 1 |
Error (see error message) |
Environment variables
| Variable |
Description |
GH_TOKEN |
GitHub API token (alternative to gh auth login) |
See also