@orcapt/cli
Advanced tools
A powerful command-line tool for managing Orca projects. Set up and run your AI agent in seconds! 🚀
orcapt kickstart <language>orcapt ship - Deploy Docker images to AWS Lambda in one command!.env files and --env flags# Install globally via npm
npm install -g @orcapt/cli
# Or use it directly with npx (no installation needed)
npx @orcapt/cli kickstart python
# Clone the repository
git clone https://github.com/Orcapt/orca-cli
cd orca-cli
# Install dependencies
npm install
# Link globally
npm link
Make sure you have these installed:
First, authenticate with Orca:
orcapt login
Create and run a new Orca Python agent in one command:
orcapt kickstart python
That's it! This will:
orca-kickstart directoryorcapt loginAuthenticate with Orca platform.
orcapt login
orcapt logoutClear stored credentials.
orcapt logout
orcapt statusCheck authentication status and workspace info.
orcapt status
orcapt kickstart <language>Quick setup for a new Orca project in your preferred language.
python - Python-based agent (FastAPI + OpenAI) ✅ Available nownode - Node.js-based agent (Express + OpenAI) ✅ Available nowgo - Go-based agent 🚧 Coming soonorcapt kickstart pythonSet 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 nodeSet 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
# 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 fileExamples:
# 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:
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
orcapt lambda listList 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
Manage S3-compatible storage buckets and files.
# 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
# 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
Create and manage PostgreSQL databases.
# Create database
orcapt db create
# List all databases
orcapt db list
# Delete database
orcapt db remove my-database
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
$ 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
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
src/commands/:// src/commands/mycommand.js
async function myCommand(options) {
console.log("Hello from my command!");
}
module.exports = myCommand;
bin/orca.js:const myCommand = require("../src/commands/mycommand");
program.command("mycommand").description("My custom command").action(myCommand);
"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
"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
"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
orca_env\Scripts\python.exeorca_env/bin/pythonIf 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
Orca CLI is designed to support multiple programming languages:
Want to contribute a starter kit in your favorite language? Check out our Contributing Guide!
To publish this package to npm:
# Login to npm
npm login
# Publish
npm publish
# Or publish as scoped package
npm publish --access public
Contributions are welcome! Here's how:
git checkout -b feature/amazing-featuregit commit -m 'Add amazing feature'git push origin feature/amazing-featureMIT License - see LICENSE file for details
# 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/
# 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
# 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
# 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}'
login, logout, status)ship).env file supportorcapt stop # Stop running servers
orcapt restart # Restart servers
orcapt update # Update Orca packages
orcapt config # Configure Orca settings
orcapt logs # View all logs
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
orcapt storage sync # Sync local folder to bucket
orcapt storage cdn # CDN configuration
Made with ❤️ by the Orca Team
Star ⭐ this repo if you find it helpful!
FAQs
CLI tool for managing Orca projects - Quick setup and deployment
We found that @orcapt/cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenAI rotated macOS signing certificates after a malicious Axios package reached its CI pipeline in a broader software supply chain attack.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.