https://ralphstarter.ai/assets/js/7fef215d.1d2ad154.js

1"use strict";(globalThis.webpackChunkdocs=globalThis.webpackChunkdocs||[]).push([[8349],{416(e,n,r){r.d(n,{R:()=>d,x:()=>l});var s=r(9471);const i={},t=s.createContext(i);function d(e){const n=s.useContext(t);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:d(e.components),s.createElement(t.Provider,{value:n},e.children)}},6965(e,n,r){r.r(n),r.d(n,{assets:()=>c,contentTitle:()=>l,default:()=>h,frontMatter:()=>d,metadata:()=>s,toc:()=>o});const s=JSON.parse('{"id":"cli/run","title":"run","description":"Run an autonomous AI coding loop","source":"@site/docs/cli/run.md","sourceDirName":"cli","slug":"/cli/run","permalink":"/docs/cli/run","draft":false,"unlisted":false,"editUrl":"https://github.com/multivmlabs/ralph-starter/tree/main/docs/docs/cli/run.md","tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"sidebar_position":1,"title":"run","description":"Run an autonomous AI coding loop","keywords":["cli","run","command","coding loop"]},"sidebar":"docsSidebar","previous":{"title":"Claude Desktop","permalink":"/docs/mcp/claude-desktop"},"next":{"title":"fix","permalink":"/docs/cli/fix"}}');var i=r(2615),t=r(416);const d={sidebar_position:1,title:"run",description:"Run an autonomous AI coding loop",keywords:["cli","run","command","coding loop"]},l="ralph-starter run",c={},o=[{value:"Synopsis",id:"synopsis",level:2},{value:"Description",id:"description",level:2},{value:"Arguments",id:"arguments",level:2},{value:"Options",id:"options",level:2},{value:"Examples",id:"examples",level:2},{value:"Basic Usage",id:"basic-usage",level:3},{value:"With Git Automation",id:"with-git-automation",level:3},{value:"With Validation",id:"with-validation",level:3},{value:"From External Sources",id:"from-external-sources",level:3},{value:"Project Location",id:"project-location",level:3},{value:"From PRD File",id:"from-prd-file",level:3},{value:"Advanced",id:"advanced",level:3},{value:"Behavior",id:"behavior",level:2},{value:"Exit Codes",id:"exit-codes",level:2},{value:"See Also",id:"see-also",level:2}];function a(e){const n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,t.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"ralph-starter-run",children:"ralph-starter run"})}),"\n",(0,i.jsx)(n.p,{children:"Run an autonomous AI coding loop."}),"\n",(0,i.jsx)(n.h2,{id:"synopsis",children:"Synopsis"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"ralph-starter run [task] [options]\n"})}),"\n",(0,i.jsx)(n.h2,{id:"description",children:"Description"}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"run"})," command executes an autonomous coding loop. The AI agent works on tasks iteratively until completion."]}),"\n",(0,i.jsx)(n.h2,{id:"arguments",children:"Arguments"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{children:"Argument"}),(0,i.jsx)(n.th,{children:"Description"})]})}),(0,i.jsx)(n.tbody,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"task"})}),(0,i.jsx)(n.td,{children:"Optional task description. If not provided, uses the implementation plan."})]})})]}),"\n",(0,i.jsx)(n.h2,{id:"options",children:"Options"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{children:"Option"}),(0,i.jsx)(n.th,{children:"Description"}),(0,i.jsx)(n.th,{children:"Default"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--auto"})}),(0,i.jsx)(n.td,{children:"Skip permission prompts"}),(0,i.jsx)(n.td,{children:"false"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--commit"})}),(0,i.jsx)(n.td,{children:"Auto-commit after each task"}),(0,i.jsx)(n.td,{children:"false"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--push"})}),(0,i.jsx)(n.td,{children:"Push commits to remote"}),(0,i.jsx)(n.td,{children:"false"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--pr"})}),(0,i.jsx)(n.td,{children:"Create pull request when done"}),(0,i.jsx)(n.td,{children:"false"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--vali

1date"})}),(0,i.jsx)(n.td,{children:"Run tests/lint/build after iterations"}),(0,i.jsx)(n.td,{children:"false"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--prd <file>"})}),(0,i.jsx)(n.td,{children:"Read tasks from markdown PRD"}),(0,i.jsx)(n.td,{children:"-"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--agent <name>"})}),(0,i.jsx)(n.td,{children:"Specify agent (claude-code, cursor, codex, opencode)"}),(0,i.jsx)(n.td,{children:"auto-detect"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--max-iterations <n>"})}),(0,i.jsx)(n.td,{children:"Maximum loop iterations"}),(0,i.jsx)(n.td,{children:"50"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--from <source>"})}),(0,i.jsx)(n.td,{children:"Fetch spec from source"}),(0,i.jsx)(n.td,{children:"-"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--project <name>"})}),(0,i.jsx)(n.td,{children:"Project filter for sources"}),(0,i.jsx)(n.td,{children:"-"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--label <name>"})}),(0,i.jsx)(n.td,{children:"Label filter for sources"}),(0,i.jsx)(n.td,{children:"-"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--status <status>"})}),(0,i.jsx)(n.td,{children:"Status filter for sources"}),(0,i.jsx)(n.td,{children:"-"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--limit <n>"})}),(0,i.jsx)(n.td,{children:"Max items from source"}),(0,i.jsx)(n.td,{children:"20"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--issue <n>"})}),(0,i.jsx)(n.td,{children:"Specific issue number (for GitHub)"}),(0,i.jsx)(n.td,{children:"-"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:(0,i.jsx)(n.code,{children:"--output-dir <path>"})}),(0,i.jsx)(n.td,{children:"Directory to run the task in"}),(0,i.jsx)(n.td,{children:"cwd"})]})]})]}),"\n",(0,i.jsx)(n.h2,{id:"examples",children:"Examples"}),"\n",(0,i.jsx)(n.h3,{id:"basic-usage",children:"Basic Usage"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'# Run a single task\nralph-starter run "build a todo app with React"\n\n# Run from implementation plan\nralph-starter run\n'})}),"\n",(0,i.jsx)(n.h3,{id:"with-git-automation",children:"With Git Automation"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'# Auto-commit changes\nralph-starter run "add login page" --commit\n\n# Commit and push\nralph-starter run "fix bug" --commit --push\n\n# Full automation with PR\nralph-starter run "add feature" --commit --push --pr\n'})}),"\n",(0,i.jsx)(n.h3,{id:"with-validation",children:"With Validation"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'# Run tests/lint/build after each iteration\nralph-starter run "refactor auth" --validate\n\n# Combine with commit\nralph-starter run "add tests" --commit --validate\n'})}),"\n",(0,i.jsx)(n.h3,{id:"from-external-sources",children:"From External Sources"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'# From URL\nralph-starter run --from https://example.com/spec.md\n\n# From GitHub\nralph-starter run --from github --project owner/repo --label "ready"\n\n# From a specific GitHub issue\nralph-starter run --from github --project owner/repo --issue 123\n\n# From Linear\nralph-starter run --from linear --label "in-progress"\n'})}),"\n",(0,i.jsx)(n.h3,{id:"project-location",children:"Project Location"}),"\n",(0,i.jsx)(n.p,{children:"When fetching from integration sources (GitHub, Linear, Notion), you'll be prompted where to run the task:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:"? Where do you want to run this task?\n  \u276f Current directory (/Users/you/current)\n    Create new project folder\n    Enter custom path\n"})}),"\n",(0,i.jsx)(n.p,{children:"To skip the prompt:"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"# Use --output-dir to specify the directory\nralph-starter run --from github --project owner/repo --issue 42 --output-dir ~/projects/new-app\n\n# Use --auto for non-interactive mode (uses current directory)\nralph-starter run --from github --project owner/repo --issue 42 --auto\n"})}),"\n",(0,i.jsx)(n.h3,{id:"from-prd-file",children:"From PRD File"}),"\n",(0,i.jsxs)(n.p,{children:["Work through tasks from a Product Requirements Document (PRD) file. The standard ralph-wiggum filename is ",(0,i.jsx)(n.code,{children:"PRD.md"}),":"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:"# Run tasks from PRD.md (standard filename)\nralph-starter run --prd PRD.md\n\n# Or specify a custom path\nralph-starter run --prd ./specs/feature-prd.md\n\n# Combine with automation\nralph-starter run --prd PRD.md --commit --vali

1date\n"})}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"PRD.md Format Example:"})}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-markdown",children:"# User Authentication\n\nImplement secure authentication for the application.\n\n## Backend\n- [ ] Create user model with email/password\n- [ ] Implement JWT token generation\n- [ ] Add password hashing with bcrypt\n\n## Frontend\n- [ ] Build login form component\n- [ ] Add session management\n- [ ] Handle authentication errors\n"})}),"\n",(0,i.jsx)(n.p,{children:"The agent will:"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["Parse tasks from checkbox format (",(0,i.jsx)(n.code,{children:"- [ ]"})," / ",(0,i.jsx)(n.code,{children:"- [x]"}),")"]}),"\n",(0,i.jsx)(n.li,{children:"Work through pending tasks one by one"}),"\n",(0,i.jsx)(n.li,{children:"Track progress (completed vs pending)"}),"\n",(0,i.jsx)(n.li,{children:"Group tasks by section headers"}),"\n",(0,i.jsxs)(n.li,{children:["Mark tasks complete by changing ",(0,i.jsx)(n.code,{children:"[ ]"})," to ",(0,i.jsx)(n.code,{children:"[x]"})]}),"\n"]}),"\n",(0,i.jsx)(n.h3,{id:"advanced",children:"Advanced"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-bash",children:'# Specify agent\nralph-starter run "build API" --agent claude-code\n\n# Limit iterations\nralph-starter run "complex task" --max-iterations 100\n\n# Full automation\nralph-starter run --auto --commit --validate --max-iterations 30\n'})}),"\n",(0,i.jsx)(n.h2,{id:"behavior",children:"Behavior"}),"\n",(0,i.jsxs)(n.ol,{children:["\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Task Resolution"}),":"]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["If ",(0,i.jsx)(n.code,{children:"task"})," provided \u2192 use that task"]}),"\n",(0,i.jsxs)(n.li,{children:["If ",(0,i.jsx)(n.code,{children:"--from"})," provided \u2192 fetch spec from source"]}),"\n",(0,i.jsxs)(n.li,{children:["If ",(0,i.jsx)(n.code,{children:"--prd"})," provided \u2192 parse tasks from PRD file"]}),"\n",(0,i.jsx)(n.li,{children:"Otherwise \u2192 read from IMPLEMENTATION_PLAN.md"}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Loop Execution"}),":"]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:"Agent works on task"}),"\n",(0,i.jsxs)(n.li,{children:["If ",(0,i.jsx)(n.code,{children:"--validate"})," \u2192 run validation commands"]}),"\n",(0,i.jsx)(n.li,{children:"If validation fails \u2192 agent fixes issues"}),"\n",(0,i.jsxs)(n.li,{children:["If ",(0,i.jsx)(n.code,{children:"--commit"})," \u2192 commit changes"]}),"\n",(0,i.jsx)(n.li,{children:"Repeat until task complete or max iterations"}),"\n"]}),"\n"]}),"\n",(0,i.jsxs)(n.li,{children:["\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Completion"}),":"]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:["If ",(0,i.jsx)(n.code,{children:"--push"})," \u2192 push to remote"]}),"\n",(0,i.jsxs)(n.li,{children:["If ",(0,i.jsx)(n.code,{children:"--pr"})," \u2192 create pull request"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h2,{id:"exit-codes",children:"Exit Codes"}),"\n",(0,i.jsxs)(n.table,{children:[(0,i.jsx)(n.thead,{children:(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.th,{children:"Code"}),(0,i.jsx)(n.th,{children:"Description"})]})}),(0,i.jsxs)(n.tbody,{children:[(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:"0"}),(0,i.jsx)(n.td,{children:"Success"})]}),(0,i.jsxs)(n.tr,{children:[(0,i.jsx)(n.td,{children:"1"}),(0,i.jsx)(n.td,{children:"Error (validation failed, agent error, etc.)"})]})]})]}),"\n",(0,i.jsx)(n.h2,{id:"see-also",children:"See Also"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.a,{href:"/docs/cli/init",children:"ralph-starter init"})}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.a,{href:"/docs/cli/plan",children:"ralph-starter plan"})}),"\n",(0,i.jsx)(n.li,{children:(0,i.jsx)(n.a,{href:"/docs/sources/overview",children:"Input Sources"})}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(a,{...e})}):a(e)}}}]);