This guide walks you through installing Shep AI CLI and creating your first feature.
npm install -g pnpm)Install Shep globally via pnpm:
pnpm add -g @shepai/cli
Or with npm:
npm install -g @shepai/cli
Verify installation:
shep --version
Navigate to your project directory and run Shep:
cd my-awesome-repository
shep
On first run, Shep launches a TUI wizard to configure your agent provider.
┌─────────────────────────────────────────────┐
│ Shep AI CLI Setup │
├─────────────────────────────────────────────┤
│ │
│ Welcome to Shep! │
│ Select your AI agent provider: │
│ │
│ ● Claude Code (Recommended) │
│ ○ Cursor │
│ ○ Gemini CLI │
│ ○ GitHub Copilot │
│ ○ Codeium │
│ ○ Amazon Q Developer │
│ ○ Cody (Sourcegraph) │
│ ○ Tabnine │
│ │
└─────────────────────────────────────────────┘
Note: Each provider has different capabilities and authentication methods. Claude Code is recommended for full autonomous SDLC support.
After selecting a provider, Shep prompts for authentication:
┌─────────────────────────────────────────────┐
│ Shep AI CLI Setup │
├─────────────────────────────────────────────┤
│ │
│ Configure Claude Code authentication │
│ │
│ How would you like to authenticate? │
│ │
│ ○ Use existing session │
│ ○ Set up new token │
│ │
└─────────────────────────────────────────────┘
Note: Authentication options vary by provider. Some support session reuse, others require API keys or OAuth.
If you’re already logged into your selected provider, Shep can use that session:
To use a new API token:
After authentication, Shep analyzes your repository:
Analyzing Repository... [████████░░░░░░░░] (75%)
✓ Architecture analysis complete
✓ Dependency analysis complete
● Pattern detection in progress...
○ Convention extraction pending
Note: Progress indicators: ✓ = complete, ● = in progress, ○ = pending.
This analysis runs once per repository and is cached for future sessions.
After analysis completes, start the web UI:
shep ui
✓ Web server started
Open in your browser:
http://localhost:4050/
Press Ctrl+C to stop
Navigate to http://localhost:4050/ in your browser.
The AI greets you with contextual options based on your repository:
┌──────────────────────────────────────────────┐
│ Welcome to my-app │
├──────────────────────────────────────────────┤
│ │
│ I've analyzed your React application with │
│ Express backend. What would you like to │
│ work on? │
│ │
│ Suggested features based on your codebase: │
│ │
│ □ Add user authentication │
│ □ Implement API rate limiting │
│ □ Add unit tests for API endpoints │
│ □ Other (describe your feature) │
│ │
└──────────────────────────────────────────────┘
Note: User selects a suggested feature or describes a custom one.
Select an option or describe your feature. The AI guides you through requirements:
┌──────────────────────────────────────────────────────┐
│ Requirements Gathering Conversation │
├──────────────────────────────────────────────────────┤
│ │
│ 👤 User: │
│ Add user authentication │
│ │
│ 🤖 Shep: │
│ Great! Let's define the authentication │
│ requirements. Which authentication method │
│ would you like? │
│ │
│ □ Email/password │
│ □ OAuth (Google, GitHub) │
│ □ Magic links │
│ □ All of the above │
│ │
│ 👤 User: │
│ OAuth (Google, GitHub) │
│ │
│ 🤖 Shep: │
│ Got it. For OAuth, I'll need to know: │
│ Should users be able to link multiple OAuth │
│ providers? │
│ │
│ □ Yes, allow linking multiple accounts │
│ □ No, one provider per user │
│ │
│ ...continued... │
│ │
└──────────────────────────────────────────────────────┘
Note: Conversational flow where Shep asks clarifying questions based on user selections.
Once requirements are complete, Shep generates a plan:
┌───────────────────────────────────────────────────┐
│ Feature: User Authentication | Lifecycle: Plan │
├───────────────────────────────────────────────────┤
│ │
│ ┌─ TASKS (5) ─────────────────────────────────┐ │
│ │ │ │
│ │ □ Set up OAuth provider configuration │ │
│ │ □ Create user model and migrations │ │
│ │ □ Implement OAuth callback handlers │ │
│ │ □ Add authentication middleware │ │
│ │ □ Create login/logout UI components │ │
│ │ │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ ┌─ DOCUMENTATION (3) ──────────────────────────┐ │
│ │ │ │
│ │ 📄 Product Requirements Document │ │
│ │ 📄 Technical RFC │ │
│ │ 📄 Implementation Tech Plan │ │
│ │ │ │
│ └──────────────────────────────────────────────┘ │
│ │
│ ┌─ Actions ────────────────────────────────────┐ │
│ │ [Implement] [Edit Plan] │ │
│ └──────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────────┘
Note: User can click [Implement] to start autonomous code generation or [Edit Plan] to modify tasks.
Click “Implement” to begin autonomous code generation:
Implementing: User Authentication | Progress: 2/5 tasks complete
✓ Set up OAuth provider configuration
✓ Create user model and migrations
● Implement OAuth callback handlers
└─ Creating src/routes/auth.ts
○ Add authentication middleware
○ Create login/logout UI components
Note: ✓ = completed tasks, ● = in progress (with current file being modified), ○ = pending tasks.
Large repositories may take longer. You can:
Add exclusions to .shep/config.json:
{
"analysis": {
"additionalExcludes": ["**/large-folder/**"]
}
}
Restart and let analysis complete:
shep restart
If authentication fails:
shep settings agent
If port 4050 is busy:
shep ui --port 4051
Update when:
Related docs: