Skip to content

Shippy CLI - Product Specification

Overview

Shippy is an AI-powered deployment CLI that makes infrastructure deployment fun and simple. Like Microsoft's Clippy, but actually helpful - Shippy uses Claude AI to understand natural language commands and guide users through deploying to local, Docker, and Azure environments.

Vision Statement

"It looks like you're trying to deploy infrastructure... Let me actually help with that!" 📎

Transform boring infrastructure deployment into an engaging, conversational experience where developers can use natural language OR slash commands to ship their applications.

Core Features

1. Animated Startup

  • GitHub Copilot-style colors (purple/blue gradients)
  • Shippy character animation (ASCII paperclip mascot)
  • Loading sequence with system checks
  • Professional yet friendly tone

2. Interactive Chat Interface

  • Claude Code-style conversation UI
  • Natural language input ("Deploy my app to Azure dev environment")
  • Slash commands for quick actions
  • AI-powered suggestions based on context
  • Command history (up/down arrows)

3. Slash Commands

/ship-local

  • Deploy infrastructure locally for development
  • Starts local Docker containers
  • Sets up local development environment
  • Example: /ship-local --env dev

/ship-docker

  • Build and deploy Docker containers
  • Push images to container registry
  • Run containers locally or on remote hosts
  • Example: /ship-docker --build --push

/ship-azure

  • Deploy complete Azure infrastructure
  • Orchestrates 4-layer deployment (Foundation → Substrate → AI Models → Apps)
  • Uses existing bash scripts from infrastructure/scripts/
  • Example: /ship-azure --env prod --layers all

4. Natural Language Processing

  • Powered by Claude API
  • Understands deployment intent from natural language
  • Suggests commands based on context
  • Explains what will happen before executing
  • Examples:
  • "Deploy my app to Azure dev" → /ship-azure --env dev
  • "Build my containers and push to registry" → /ship-docker --build --push
  • "Start local development environment" → /ship-local

User Experience Flow

1. User runs: shippy
   ↓
2. Shippy animated startup (3-5 seconds)
   ↓
3. Interactive prompt appears:

   📎 Shippy: "How can I help you ship today?"

   You: _
   ↓
4. User types natural language OR slash command
   ↓
5. Shippy analyzes intent with AI
   ↓
6. Shippy shows what it will do + asks confirmation
   ↓
7. User confirms (y/n)
   ↓
8. Shippy executes deployment with progress animations
   ↓
9. Shippy celebrates success OR helps debug errors
   ↓
10. Returns to interactive prompt for next command

Target Audience

Primary Users

  • Developers who need to deploy applications but find infrastructure intimidating
  • DevOps engineers who want faster deployment workflows
  • Students/learners exploring Azure deployment

User Personas

Persona 1: Junior Developer "Alex" - 2 years experience, comfortable with code, new to infrastructure - Pain: "I just want to deploy my app, why is Azure so complicated?" - Goal: Ship to dev environment without reading 50 pages of docs - Shippy helps: Natural language commands guide Alex through deployment

Persona 2: Senior Developer "Sam" - 8 years experience, knows infrastructure but values speed - Pain: "I know what I want, just let me do it fast" - Goal: Deploy to prod in <2 minutes - Shippy helps: Slash commands provide instant deployment without UI clicks

Technical Architecture

Tech Stack

  • Language: TypeScript/Node.js
  • CLI Framework: Commander.js
  • UI Libraries:
  • chalk - Terminal colors
  • ora - Spinners
  • inquirer - Interactive prompts
  • gradient-string - Color gradients (Copilot-style)
  • figlet - ASCII art
  • AI: Anthropic Claude API
  • Deployment: Wraps existing bash scripts in infrastructure/scripts/

Folder Structure

infrastructure/shippy/
├── src/
│   ├── cli.ts                 # Main CLI entry point
│   ├── animation.ts           # Startup animations
│   ├── interactive.ts         # Chat-like interface
│   ├── ai-handler.ts          # Claude API integration
│   ├── commands/
│   │   ├── ship-local.ts      # /ship-local command
│   │   ├── ship-docker.ts     # /ship-docker command
│   │   └── ship-azure.ts      # /ship-azure command
│   └── utils/
│       ├── colors.ts          # Copilot-style color schemes
│       └── shippy-art.ts      # ASCII art for Shippy character
├── dist/                      # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Command Specifications

/ship-local

Purpose: Start local development environment

Options: - --env <name> - Environment name (default: dev) - --services <list> - Which services to start (default: all) - --port <number> - Override default ports

Example: 

📎 You: /ship-local --env dev

📎 Shippy: "I'll start your local dev environment:
  - API on port 8000
  - UI on port 5173
  - 3 MCP servers on ports 8010-8012

  Sound good?"

You: y

📎 Shippy: "Shipping locally! 🚀"
[Progress animations...]
✅ All services running!

/ship-docker

Purpose: Build and deploy Docker containers

Options: - --build - Build images - --push - Push to registry - --registry <url> - Registry URL (default: from config) - --tag <version> - Image tag (default: git SHA)

Example: 

📎 You: /ship-docker --build --push

📎 Shippy: "I'll build 5 images and push to ACR:
  - loan-defenders-ui
  - loan-defenders-api
  - mcp-application-verification
  - mcp-document-processing
  - mcp-financial-calculations

  Proceed?"

You: y

📎 Shippy: "Building containers! 🔨"
[Progress animations...]
✅ All images pushed to ACR!

/ship-azure

Purpose: Deploy to Azure infrastructure

Options: - --env <name> - Environment (dev/staging/prod) - --layers <list> - Which layers to deploy (default: all) - Options: foundation, substrate, ai-models, apps, all - --region <name> - Azure region (default: eastus) - --skip-confirm - Auto-approve deployment

Example: 

📎 You: /ship-azure --env dev --layers all

📎 Shippy: "I'll deploy all 4 layers to Azure (dev):
  🏗️  Foundation (~12 min)
  🔧 Substrate (~7 min)
  🧠 AI Models (~4 min)
  🚀 Apps (~2 min)

  Total: ~25 minutes

  Ready to ship?"

You: y

📎 Shippy: "Shipping to Azure! ☁️"
[Progress animations with Shippy comments...]
✅ All layers deployed!

Natural Language Examples

User Input Shippy Understanding Command Executed
"Deploy to Azure dev" Deploy Azure dev environment /ship-azure --env dev
"Build my containers" Build Docker images /ship-docker --build
"Start local dev" Start local environment /ship-local
"Ship everything to prod" Full Azure prod deployment /ship-azure --env prod --layers all
"Just the apps layer to staging" Deploy only apps to staging /ship-azure --env staging --layers apps
"Push images to registry" Build and push Docker images /ship-docker --build --push

Success Metrics

Adoption Metrics

  • Active users: 80%+ of team using Shippy for deployments
  • Frequency: 5+ deployments per user per week
  • NPS: >50 (world-class product)

Efficiency Metrics

  • Time to first deployment: <5 minutes (vs 2 hours manual)
  • Deployment success rate: >90% on first attempt
  • Error recovery time: <5 minutes (AI-guided fixes)

Engagement Metrics

  • Natural language usage: 40%+ of commands use NLP (not slash)
  • Command completion rate: >85% of started deployments complete
  • Return usage: 70%+ use Shippy again within 7 days

Development Roadmap

Phase 0: MVP (Week 1)

  • ✅ Animated startup with Shippy character
  • ✅ Interactive chat interface
  • ✅ /ship-local command (basic)
  • ✅ Natural language parsing (Claude API)

Phase 1: Core Commands (Week 2)

  • ✅ /ship-docker command (build + push)
  • ✅ /ship-azure command (all 4 layers)
  • ✅ Progress animations with Shippy comments
  • ✅ Error handling with AI diagnosis

Phase 2: Polish (Week 3)

  • ✅ Command history (up/down arrows)
  • ✅ Auto-complete for slash commands
  • ✅ Configuration file support
  • ✅ Comprehensive error messages

Phase 3: Advanced (Week 4+)

  • Multi-environment management
  • Deployment rollback
  • Cost estimation
  • Integration with CI/CD

Design Principles

1. Fun but Professional

  • Shippy has personality but doesn't distract
  • Humor enhances, doesn't annoy
  • Enterprise-ready despite playful character

2. Natural Language First

  • Slash commands are shortcuts, not primary UX
  • AI should understand intent from conversational input
  • Provide suggestions, not just command execution

3. Transparent Operations

  • Always show what will happen before executing
  • Provide detailed progress during deployment
  • Explain errors in plain English

4. Speed for Power Users

  • Slash commands bypass AI for instant execution
  • Support flags for all customization
  • Enable --skip-confirm for automation

Competitive Differentiation

vs Azure CLI

  • Shippy: Natural language, AI-powered, character-driven
  • Azure CLI: Technical, manual, no guidance

vs Terraform/Pulumi

  • Shippy: No learning curve, conversational, wraps existing scripts
  • Terraform/Pulumi: Requires HCL/code knowledge, steep learning

vs GitHub Copilot CLI

  • Shippy: Deployment-focused, Azure-specific, persistent chat session
  • Copilot CLI: General-purpose, one-off commands, no state

Risk Mitigation

Risk: Users find Shippy gimmicky

Mitigation: Provide --no-character flag for plain mode, focus on utility over personality

Risk: AI gives incorrect suggestions

Mitigation: Always show preview + confirmation, log all AI suggestions for improvement

Risk: Natural language is too slow

Mitigation: Slash commands provide fast path, cache common intents

Success Criteria (Launch Ready)

  • ✅ All 3 slash commands working (/ship-local, /ship-docker, /ship-azure)
  • ✅ Natural language understands 10+ common deployment intents
  • ✅ Animated startup completes in <5 seconds
  • ✅ 5 successful deployments by beta testers
  • ✅ NPS >40 from initial users
  • ✅ Documentation complete (README, command reference)

Version: 1.0 Last Updated: 2025-01-26 Owner: Infrastructure Team Status: In Development