@deftai/directive-content 0.55.0

package/deployments/agentuity/via-cli.md

@@ -0,0 +1,380 @@
+# Deploy via Agentuity CLI
+
+The primary and recommended method for deploying agents to Agentuity. The CLI provides the complete development lifecycle from project creation through production deployment.
+
+## Prerequisites
+
+- macOS, Linux, or WSL on Windows
+- Node.js 18+ or Bun (for TypeScript/JavaScript agents)
+- Python 3.9+ (for Python agents)
+- Git (optional, for version control)
+
+## Installation
+
+### macOS / Linux
+
+```bash
+# Install via install script (recommended)
+curl -fsS https://agentuity.sh | sh
+
+# Or via Homebrew (macOS)
+brew install agentuity
+```
+
+### Windows (WSL Required)
+
+```bash
+# Run from WSL terminal
+curl -fsS https://agentuity.sh | sh
+```
+
+### Verify Installation
+
+```bash
+agentuity version
+agentuity --help
+```
+
+## Quick Start
+
+### 1. Create a New Project
+
+```bash
+# Interactive creation with templates
+agentuity create
+
+# You'll be prompted to choose:
+# - Project name
+# - Runtime (TypeScript, Python, Bun)
+# - Template (basic, chat, research, etc.)
+```
+
+### 2. Start Local Development
+
+```bash
+cd my-agent-project
+agentuity dev
+
+# Your agent will be available at http://localhost:3500
+# Hot reload enabled - changes apply instantly
+```
+
+### 3. Deploy to Production
+
+```bash
+# Deploy to Agentuity Cloud
+agentuity deploy
+
+# Or specify target
+agentuity cloud deploy --dir ./my-project
+```
+
+## Project Structure
+
+After running `agentuity create`, your project will have:
+
+```
+my-agent/
+├── agentuity.yaml          # Project configuration
+├── src/
+│   └── agents/            # Agent definitions
+│       └── index.ts       # Main agent
+├── api/                   # API routes (optional)
+├── web/                   # React frontend (optional)
+└── package.json           # Dependencies
+```
+
+## Core CLI Commands
+
+### Project Management
+
+```bash
+# Create new agent in existing project
+agentuity agent create [name]
+
+# List all agents
+agentuity agent list
+
+# Delete an agent
+agentuity agent delete [name]
+```
+
+### Development
+
+```bash
+# Start dev server
+agentuity dev
+
+# Run with specific port
+agentuity dev --port 4000
+
+# Enable debug logging
+agentuity dev --log-level debug
+```
+
+### Deployment
+
+```bash
+# Deploy to production
+agentuity deploy
+
+# Deploy with dry-run (validate only)
+agentuity deploy --dry-run
+
+# Deploy specific directory
+agentuity deploy --dir ./my-project
+
+# Deploy with explanation
+agentuity deploy --explain
+```
+
+### Environment Management
+
+```bash
+# List environment variables
+agentuity env
+
+# Set environment variable
+agentuity env set KEY=value
+
+# Delete environment variable
+agentuity env delete KEY
+```
+
+### Authentication
+
+```bash
+# Login to Agentuity Cloud
+agentuity auth login
+
+# Logout
+agentuity auth logout
+
+# Check auth status
+agentuity auth status
+```
+
+### API Key Management
+
+```bash
+# Create API key
+agentuity apikey create
+
+# List API keys
+agentuity apikey list
+
+# Revoke API key
+agentuity apikey revoke [key-id]
+```
+
+## Agent Configuration
+
+### Basic Agent (TypeScript)
+
+```typescript
+// src/agents/chat.ts
+import { createAgent } from '@agentuity/runtime';
+import { s } from '@agentuity/schema';
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const agent = createAgent('chat', {
+  description: 'A simple chat agent',
+  schema: {
+    input: s.object({
+      message: s.string()
+    }),
+    output: s.object({
+      response: s.string()
+    })
+  },
+  handler: async (ctx, { message }) => {
+    const { text } = await generateText({
+      model: openai('gpt-4'),
+      prompt: message
+    });
+    return { response: text };
+  }
+});
+
+export default agent;
+```
+
+### agentuity.yaml Configuration
+
+```yaml
+name: my-agent
+description: My AI agent project
+version: 1.0.0
+
+runtime:
+  type: nodejs
+  version: "18"
+
+agents:
+  - name: chat
+    path: src/agents/chat.ts
+    auth: api-key
+
+env:
+  - OPENAI_API_KEY
+  - DATABASE_URL
+```
+
+## Advanced Features
+
+### Offline Development
+
+Agentuity CLI works offline by default:
+
+```bash
+# No account required to start building
+agentuity create --offline
+
+# Deploy when ready
+agentuity deploy
+```
+
+### JSON Output for Automation
+
+```bash
+# Get agent info as JSON
+agentuity agent list --json
+
+# Deploy with JSON output
+agentuity deploy --json
+```
+
+### Schema Discovery
+
+```bash
+# Discover available schemas
+agentuity schema list
+
+# Validate agent schemas
+agentuity schema validate
+```
+
+## Deployment Options
+
+### Standard Cloud Deployment
+
+```bash
+# Deploy to Agentuity managed infrastructure
+agentuity deploy
+
+# Features:
+# - Global edge network
+# - Sub-100ms cold starts
+# - Automatic scaling
+# - Built-in SSL/DNS
+```
+
+### Custom Domain
+
+```bash
+# Configure custom domain
+agentuity domain add example.com
+
+# SSL certificates managed automatically
+```
+
+### Rollback
+
+```bash
+# List deployments
+agentuity deployments list
+
+# Rollback to previous version
+agentuity rollback [deployment-id]
+```
+
+## Monitoring and Debugging
+
+### View Logs
+
+```bash
+# Stream live logs
+agentuity logs --follow
+
+# Filter by agent
+agentuity logs --agent chat
+
+# View last 100 lines
+agentuity logs --tail 100
+```
+
+### Inspect Agent
+
+```bash
+# Get agent details
+agentuity agent inspect [name]
+
+# View agent configuration
+agentuity agent config [name]
+```
+
+## Best Practices
+
+1. **Use Templates**: Start with `agentuity create` templates for best practices
+2. **Environment Variables**: Never commit secrets; use `agentuity env` commands
+3. **Test Locally**: Always test with `agentuity dev` before deploying
+4. **Version Control**: Commit `agentuity.yaml` and agent code to Git
+5. **Dry Run**: Use `--dry-run` to validate before actual deployment
+
+## Troubleshooting
+
+### CLI Not Found After Installation
+
+```bash
+# Add to PATH (macOS/Linux)
+export PATH="$HOME/.agentuity/bin:$PATH"
+
+# Reload shell
+source ~/.zshrc  # or ~/.bashrc
+```
+
+### Deployment Fails
+
+```bash
+# Check auth status
+agentuity auth status
+
+# Validate configuration
+agentuity deploy --dry-run --explain
+
+# Check logs
+agentuity logs --tail 50
+```
+
+### Port Already in Use
+
+```bash
+# Use different port
+agentuity dev --port 4000
+```
+
+## Upgrading the CLI
+
+```bash
+# Upgrade to latest version
+agentuity upgrade
+
+# Or reinstall
+curl -fsS https://agentuity.sh | sh
+```
+
+## Next Steps
+
+- **Add Frontend**: Deploy React frontend with `@agentuity/react`
+- **Multi-Agent**: Coordinate multiple agents with type-safe calls
+- **Production Evals**: Enable evaluations on live traffic
+- **VPC Deployment**: See `via-vpc.md` for private cloud deployment
+- **CI/CD**: Automate with `via-github-actions.md`
+
+## References
+
+- [CLI Documentation](https://agentuity.dev/CLI)
+- [CLI GitHub Repository](https://github.com/agentuity/cli)
+- [Getting Started Guide](https://agentuity.dev/Introduction/getting-started)
+- [Agent Commands Reference](https://agentuity.dev/CLI/agent)