@orcapt/cli

@orcapt/cli

A powerful command-line tool for managing Orca projects. Set up and run your AI agent in seconds! 🚀

✨ Features

• 🎯 One Command Setup - Clone, configure, and run with orcapt kickstart <language>
• 🌐 Multi-Language Support - Python ✅ | Node.js ✅ | Go (coming soon)
• 🖥️ Cross-Platform - Works on Windows, Linux, and macOS
• 📦 No Dependencies - Just Node.js (which you already have!)
• 🎨 Beautiful UI - Colorful output with progress indicators
• ⚡ Fast - Node.js native performance
• 🔄 Process Management - Manages both backend and frontend automatically
• 🚀 Lambda Deployment - Deploy Docker images to AWS Lambda with one command
• 💾 Storage Management - Manage S3-compatible storage buckets and files
• 🗄️ Database Management - Create and manage PostgreSQL databases

🌟 What's New

Latest Features (v2.0)

• 🚀 orcapt ship - Deploy Docker images to AWS Lambda in one command!
• 📊 Real-time Progress Bar - See exactly how much of your image has been pushed
• 🔐 Environment Variables - Support for .env files and --env flags
• 💾 Storage Management - Full S3-compatible storage with buckets, files, and permissions
• 🗄️ Database Management - PostgreSQL database creation and management
• 🔑 Authentication - Secure workspace-based authentication

📦 Installation

Quick Install (Recommended)

# Install globally via npm
npm install -g @orcapt/cli

# Or use it directly with npx (no installation needed)
npx @orcapt/cli kickstart python

Install from Source

# Clone the repository
git clone https://github.com/Orcapt/orca-cli
cd orca-cli

# Install dependencies
npm install

# Link globally
npm link

🚀 Quick Start

Prerequisites

Make sure you have these installed:

• Node.js 14+ (you already have this!)
• Python 3.8+ (for Python starter kit)
• Git
• Docker (for Lambda deployments)

Authentication

First, authenticate with Orca:

orcapt login

Usage

Create and run a new Orca Python agent in one command:

orcapt kickstart python

That's it! This will:

• ✅ Check prerequisites (Python, Git, Node.js)
• 📁 Create orca-kickstart directory
• 📦 Clone the starter kit
• 🐍 Set up Python virtual environment
• 📥 Install all dependencies
• 🚀 Start backend (port 5001)
• 🎨 Start frontend (port 3000)

📖 Command Reference

Authentication Commands

orcapt login

Authenticate with Orca platform.

orcapt login

orcapt logout

Clear stored credentials.

orcapt logout

orcapt status

Check authentication status and workspace info.

orcapt status

orcapt kickstart <language>

Quick setup for a new Orca project in your preferred language.

Available Languages:

• python - Python-based agent (FastAPI + OpenAI) ✅ Available now
• node - Node.js-based agent (Express + OpenAI) ✅ Available now
• go - Go-based agent 🚧 Coming soon

orcapt kickstart python

Set up a Python-based Orca agent with FastAPI and OpenAI.

Options:

-d, --directory <name>      Directory name (default: "orca-kickstart")
-p, --port <number>         Frontend port (default: 3000)
-a, --agent-port <number>   Backend port (default: 5001)
--no-start                  Skip auto-starting servers

Examples:

# Basic usage
orcapt kickstart python

# Custom directory name
orcapt kickstart python --directory my-awesome-agent

# Custom ports
orcapt kickstart python --port 8080 --agent-port 8000

# Setup without auto-start
orcapt kickstart python --no-start

# All options combined
orcapt kickstart python -d my-agent -p 4000 -a 5000

orcapt kickstart node

Set up a Node.js-based Orca agent with Express and OpenAI.

Options: Same as Python (see above)

Examples:

# Basic usage
orcapt kickstart node

# Custom directory name
orcapt kickstart node --directory my-node-agent

# Custom ports
orcapt kickstart node --port 8080 --agent-port 8000

# All options combined
orcapt kickstart node -d my-agent -p 4000 -a 5000

Coming Soon:

# Go agent (coming soon)
orcapt kickstart go

🚀 orcapt ship <function-name>

Deploy Docker images to AWS Lambda with one command!

Syntax:

orcapt ship <function-name> [options]

Options:

• --image <image> - Docker image (registry/image:tag) [Required]
• --memory <mb> - Memory in MB (default: 512)
• --timeout <seconds> - Timeout in seconds (default: 30)
• --env <key=value> - Environment variable (can be repeated)
• --env-file <path> - Path to .env file

Examples:

# Basic deployment
orcapt ship my-api --image=my-app:latest

# With custom memory and timeout
orcapt ship my-api \
  --image=my-app:latest \
  --memory=1024 \
  --timeout=60

# With environment variables
orcapt ship my-api \
  --image=my-app:latest \
  --env DATABASE_URL=postgres://... \
  --env API_KEY=secret123 \
  --env DEBUG=true

# With .env file
orcapt ship my-api \
  --image=my-app:latest \
  --env-file=.env

# Override .env with specific values
orcapt ship my-api \
  --image=my-app:latest \
  --env-file=.env \
  --env DEBUG=false

What it does:

• ✅ Checks Docker installation
• ✅ Validates local image exists
• ✅ Requests ECR credentials from backend
• ✅ Logs into AWS ECR
• ✅ Tags image for ECR
• ✅ Pushes image to ECR (with progress bar!)
• ✅ Creates/updates Lambda function
• ✅ Configures Function URL
• ✅ Returns invoke URL

Output:

============================================================
🚀 Deploying Lambda Function
============================================================

Function:   my-api
Image:      my-app:latest
Memory:     1024 MB
Timeout:    60s
Workspace:  my-workspace
Env Vars:   3 variables

✓ Docker is installed and running
✓ Found image 'my-app:latest' (259 MB)
✓ ECR credentials received
✓ Logged into ECR
✓ Image tagged for ECR
✓ Image pushed to ECR [████████████████████] 100% (3/3 layers)
✓ Lambda function created
✓ API Gateway configured
✓ Deployment completed

============================================================
✓ Function deployed successfully!
============================================================

Function Details:
  Name:         my-api
  Image:        123456789.dkr.ecr.us-east-1.amazonaws.com/...
  Region:       us-east-1
  Memory:       1024 MB
  Timeout:      60s
  Status:       Active

Invoke URL:
  https://abc123.lambda-url.us-east-1.on.aws

Try it:
  curl https://abc123.lambda-url.us-east-1.on.aws

Lambda Management Commands

orcapt lambda list

List all Lambda functions in your workspace.

orcapt lambda list

orcapt lambda info <function-name>

Get detailed information about a Lambda function.

orcapt lambda info my-api

orcapt lambda invoke <function-name>

Invoke a Lambda function.

# Simple invoke
orcapt lambda invoke my-api

# With JSON payload
orcapt lambda invoke my-api --payload '{"key": "value"}'

orcapt lambda logs <function-name>

View Lambda function logs.

# Recent logs
orcapt lambda logs my-api

# Stream logs in real-time
orcapt lambda logs my-api --tail

# Logs from last hour
orcapt lambda logs my-api --since 1h

orcapt lambda remove <function-name>

Delete a Lambda function.

orcapt lambda remove my-api

💾 Storage Commands

Manage S3-compatible storage buckets and files.

Bucket Management

# Create bucket
orcapt storage bucket create my-bucket

# Create public bucket with versioning
orcapt storage bucket create my-bucket --public --versioning

# List all buckets
orcapt storage bucket list

# Get bucket info
orcapt storage bucket info my-bucket

# Delete bucket
orcapt storage bucket delete my-bucket

# Force delete (removes all files)
orcapt storage bucket delete my-bucket --force

File Management

# Upload file
orcapt storage upload my-bucket ./file.txt

# Upload to specific folder
orcapt storage upload my-bucket ./file.txt --folder=/documents

# Upload as public file
orcapt storage upload my-bucket ./file.txt --public

# List files in bucket
orcapt storage files my-bucket

# List files in folder
orcapt storage files my-bucket --folder=/documents

# Download file
orcapt storage download my-bucket file.txt

# Download to specific path
orcapt storage download my-bucket file.txt ./downloads/

# Delete file
orcapt storage delete my-bucket file.txt

🗄️ Database Commands

Create and manage PostgreSQL databases.

# Create database
orcapt db create

# List all databases
orcapt db list

# Delete database
orcapt db remove my-database

🎨 UI Commands

Manage Orca UI installation.

# Install UI globally
orcapt ui init

# Start UI
orcapt ui start

# Start with custom ports
orcapt ui start --port 3000 --agent-port 5001

# Remove UI
orcapt ui remove

🎬 What It Looks Like

$ orcapt kickstart python

============================================================
🚀 Orca Kickstart - Python
============================================================

✓ Python found: python3
✓ Git found
✓ Node.js/npm found
✓ npx found

► Creating directory: orca-kickstart
✓ Created directory: /path/to/orca-kickstart

✓ Repository cloned successfully
✓ Virtual environment created
✓ Dependencies installed

============================================================
✓ Setup completed successfully!
============================================================

✓ Backend started (PID: 12345)
✓ Frontend started (PID: 12346)

============================================================
🎉 Orca is running!
============================================================

Frontend: http://localhost:3000
Backend:  http://localhost:5001

⚠ Press Ctrl+C to stop both servers

🛠️ Development

Project Structure

orca-cli/
├── bin/
│   └── orca.js                    # CLI entry point (executable)
├── src/
│   ├── commands/
│   │   ├── kickstart-python.js     # Python kickstart
│   │   ├── kickstart-node.js       # Node.js kickstart
│   │   ├── login.js                # Authentication
│   │   ├── lambda.js               # Lambda deployment
│   │   ├── storage.js              # Storage management
│   │   ├── db.js                   # Database management
│   │   ├── ui.js                   # UI management
│   │   └── fetch-doc.js            # Documentation fetcher
│   ├── utils/
│   │   └── docker-helper.js        # Docker utilities
│   └── config.js                   # Configuration
├── package.json                    # Package configuration
├── README.md                       # This file
├── ENVIRONMENT_VARIABLES.md        # Environment variables guide
├── PROGRESS_BAR_ENHANCEMENT.md     # Progress bar documentation
└── .gitignore                      # Git ignore patterns

Adding New Commands

• Create a new file in src/commands/:

// src/commands/mycommand.js
async function myCommand(options) {
  console.log("Hello from my command!");
}

module.exports = myCommand;

• Register it in bin/orca.js:

const myCommand = require("../src/commands/mycommand");

program.command("mycommand").description("My custom command").action(myCommand);

Dependencies

• commander - CLI framework with elegant syntax
• chalk - Terminal styling and colors
• ora - Beautiful terminal spinners
• inquirer - Interactive prompts
• simple-git - Git operations
• cross-spawn - Cross-platform process spawning

🐛 Troubleshooting

Kickstart Issues

"Python not found"

# Install Python 3.8+
# macOS: brew install python3
# Windows: https://www.python.org/downloads/
# Linux: sudo apt install python3

"Git not found"

# Install Git
# macOS: brew install git
# Windows: https://git-scm.com/downloads
# Linux: sudo apt install git

"Directory already exists"

# Use a different directory name
orcapt kickstart python --directory my-other-project

# Or remove the existing directory
rm -rf orca-kickstart

"Port already in use"

# Use different ports
orcapt kickstart python --port 4000 --agent-port 5000

# Or find and kill the process using the port
# macOS/Linux: lsof -ti:3000 | xargs kill
# Windows: netstat -ano | findstr :3000

Lambda Deployment Issues

"Docker not found"

# Install Docker
# macOS: brew install --cask docker
# Windows: https://docs.docker.com/desktop/install/windows-install/
# Linux: https://docs.docker.com/engine/install/

"Docker image not found"

# Build your image first
docker build -t my-app:latest .

# Check if image exists
docker images | grep my-app

"ECR login failed"

# Check your authentication
orcapt status

# Re-login if needed
orcapt logout
orcapt login

# Check backend is running and AWS credentials are configured

"Lambda deployment timeout"

# Increase timeout
orcapt ship my-api --image=my-app:latest --timeout=120

# Check image size (should be < 10 GB)
docker images | grep my-app

"Environment variables not working"

# Check .env file format
cat .env

# Test with explicit --env flags
orcapt ship my-api --image=my-app:latest --env DEBUG=true

# Check Lambda function info
orcapt lambda info my-api

Storage Issues

"Bucket already exists"

# Use a different bucket name
orcapt storage bucket create my-bucket-2

# Or delete existing bucket
orcapt storage bucket delete my-bucket --force

"File upload failed"

# Check file exists
ls -lh ./file.txt

# Check bucket exists
orcapt storage bucket list

# Try with absolute path
orcapt storage upload my-bucket /full/path/to/file.txt

Platform-Specific Notes

Windows

• Uses orca_env\Scripts\python.exe
• Automatically handles Windows paths
• PowerShell and CMD supported

macOS/Linux

• Uses orca_env/bin/python
• Bash and Zsh supported

📝 Manual Setup

If you prefer to set up manually:

# After kickstart python (with --no-start)
cd orca-kickstart

# Activate virtual environment
source orca_env/bin/activate    # macOS/Linux
orca_env\Scripts\activate       # Windows

# Start backend
python main.py --dev

# In another terminal, start frontend
npx -y @orcapt/ui --port=3000 --agent-port=5001

🌐 Multi-Language Support

Orca CLI is designed to support multiple programming languages:

Currently Available:

• ✅ Python - Full support with FastAPI + OpenAI
• ✅ Node.js - Full support with Express + OpenAI

Coming Soon:

• 🚧 Go - Gin/Fiber + OpenAI

Future Languages:

• TypeScript
• Rust
• Java
• C#/.NET

Want to contribute a starter kit in your favorite language? Check out our Contributing Guide!

🚢 Publishing to npm

To publish this package to npm:

# Login to npm
npm login

# Publish
npm publish

# Or publish as scoped package
npm publish --access public

🤝 Contributing

Contributions are welcome! Here's how:

• Fork the repository
• Create your feature branch: git checkout -b feature/amazing-feature
• Commit your changes: git commit -m 'Add amazing feature'
• Push to the branch: git push origin feature/amazing-feature
• Open a Pull Request

📄 License

MIT License - see LICENSE file for details

💡 Quick Examples

Example 1: Deploy FastAPI to Lambda

# 1. Create FastAPI app
mkdir my-api && cd my-api

# 2. Create Dockerfile
cat > Dockerfile << 'EOF'
FROM public.ecr.aws/lambda/python:3.11
COPY requirements.txt .
RUN pip install -r requirements.txt --target .
COPY . .
CMD ["lambda_adapter.handler"]
EOF

# 3. Create requirements.txt
cat > requirements.txt << 'EOF'
fastapi
mangum
EOF

# 4. Create main.py
cat > main.py << 'EOF'
from fastapi import FastAPI
app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello from Lambda!"}
EOF

# 5. Create lambda_adapter.py
cat > lambda_adapter.py << 'EOF'
from mangum import Mangum
from main import app
handler = Mangum(app)
EOF

# 6. Build Docker image
docker build -t my-api:latest .

# 7. Deploy to Lambda
orcapt ship my-api --image=my-api:latest --memory=1024 --timeout=60

# 8. Test
curl https://YOUR-FUNCTION-URL/

Example 2: Deploy with Environment Variables

# Create .env file
cat > .env << 'EOF'
DATABASE_URL=postgresql://user:pass@host:5432/db
OPENAI_API_KEY=sk-...
DEBUG=false
EOF

# Deploy with .env
orcapt ship my-api \
  --image=my-api:latest \
  --env-file=.env \
  --memory=2048 \
  --timeout=120

Example 3: Storage Workflow

# 1. Create bucket
orcapt storage bucket create my-files --public

# 2. Upload files
orcapt storage upload my-files ./document.pdf
orcapt storage upload my-files ./image.png --folder=/images

# 3. List files
orcapt storage files my-files

# 4. Download file
orcapt storage download my-files document.pdf

# 5. Add permissions
orcapt storage permission add my-files \
  --target-type=user \
  --target-id=user123 \
  --read --write

Example 4: Complete Workflow

# 1. Login
orcapt login

# 2. Create database
orcapt db create

# 3. Create storage bucket
orcapt storage bucket create app-storage

# 4. Deploy Lambda function
orcapt ship my-app \
  --image=my-app:latest \
  --env DATABASE_URL=postgres://... \
  --env BUCKET_NAME=app-storage \
  --memory=1024

# 5. Check deployment
orcapt lambda info my-app

# 6. View logs
orcapt lambda logs my-app

# 7. Invoke function
orcapt lambda invoke my-app --payload '{"test": true}'

🙏 Support

• 📚 Documentation
• 🐛 Report Issues
• 💬 Discussions

🎯 Roadmap

✅ Completed Features

• ✅ Authentication (login, logout, status)
• ✅ Kickstart for Python and Node.js
• ✅ Lambda deployment with Docker (ship)
• ✅ Storage management (buckets, files, permissions)
• ✅ Database management (PostgreSQL)
• ✅ UI management
• ✅ Environment variables support
• ✅ Progress bar for Docker push
• ✅ .env file support

🚧 Coming Soon

Commands

orcapt stop            # Stop running servers
orcapt restart         # Restart servers
orcapt update          # Update Orca packages
orcapt config          # Configure Orca settings
orcapt logs            # View all logs

Lambda Features

orcapt ship --auto-scale          # Auto-scaling configuration
orcapt ship --vpc                 # VPC configuration
orcapt lambda rollback            # Rollback to previous version
orcapt lambda alias               # Manage function aliases

Storage Features

orcapt storage sync               # Sync local folder to bucket
orcapt storage cdn                # CDN configuration

Language Support

• ✅ Python - Available
• ✅ Node.js - Available
• 🚧 Go - Coming soon
• 🚧 Rust - Planned
• 🚧 TypeScript - Planned

Made with ❤️ by the Orca Team

Star ⭐ this repo if you find it helpful!