npm package: @handit.ai/cli
Description: AI-Powered Agent Instrumentation & Monitoring CLI Tool
Author: Handit Team
Latest version: 1.4.48

# Handit CLI

> **Setting up your autonomous engineer**

Stop being your AI's on-call engineer. Your autonomous engineer monitors your AI 24/7, detects issues, creates fixes, and ships them as pull requests—automatically.

## The Problem: You're Your AI's On-Call Engineer

2am failures wake you up. Your AI starts giving bad responses, customers complain, and you're debugging blind. Did the model change? Is a tool broken? Is there a logic error? Without visibility, you're playing whack-a-mole with quality issues.

Manual fixes don't scale. You spot-check responses, find problems, and wonder about the thousands of interactions you didn't see. By the time you notice issues, they've already impacted users.

Your autonomous engineer solves this by monitoring every interaction, detecting quality drops, analyzing root causes, and shipping proven fixes—all automatically.

## The Solution: Your Autonomous Engineer

🔍 **Monitors your AI interactions and detects quality issues**  
🛠️ **Generates fixes and tests them against real data**  
📝 **Creates pull requests with proven improvements**

**Time required:** Under 5 minutes  
**Prerequisites:** Handit.ai Account, Node.js, and admin access to your GitHub repository

## Set up your autonomous engineer

Your autonomous engineer setup happens in one seamless flow through the Handit CLI. Here's what will happen:

### Step 1: Install the Handit CLI

```bash
npm install -g @handit.ai/cli
```

### Step 2: Start the Setup Process

Navigate to your AI project directory and run:

```bash
handit-cli setup
```

The CLI will guide you through connecting your autonomous engineer to your AI system:

#### 🔧 Initial Connection

- Connect your Handit.ai account
- Install the Handit SDK in your project
- Configure your API key for monitoring

#### 📱 Test Your Connection

- The CLI will ask you to run your app to verify everything works
- Your autonomous engineer immediately starts monitoring your AI
- You'll see real-time data flowing in your dashboard

### Example of code the CLI generates for you:

The CLI adds tracing only to your main agent entry points - the functions that start agent execution:

**Python:**

```python
# Auto-generated by handit-cli setup
from handit_ai import tracing, configure
import os

configure(HANDIT_API_KEY=os.getenv("HANDIT_API_KEY"))

# Tracing added to your main agent function (entry point)
@tracing(agent="customer-service-agent")
async def process_customer_request(user_message: str):
    # Your existing agent logic (unchanged)
    intent = await classify_intent(user_message)      # Not traced individually
    context = await search_knowledge(intent)          # Not traced individually  
    response = await generate_response(context)       # Not traced individually
    return response
```

**JavaScript:**

```javascript
// Auto-generated by handit-cli setup
import { configure, startTracing, endTracing } from '@handit.ai/handit-ai';

configure({
  HANDIT_API_KEY: process.env.HANDIT_API_KEY
});

// Tracing added to your main agent function (entry point)
export const processCustomerRequest = async (userMessage) => {
  startTracing({ agent: "customer-service-agent" });
  try {
    // Your existing agent logic (unchanged)
    const intent = await classifyIntent(userMessage);     // Not traced individually
    const context = await searchKnowledge(intent);       // Not traced individually
    const response = await generateResponse(context);     // Not traced individually
    return response;
  } finally {
    endTracing();
  }
};
```

**Key point:** The CLI only adds tracing to your main agent functions, not to every individual function. Everything inside the traced function gets captured automatically.

## Your Autonomous Engineer is Now Active

✅ **Check your dashboard:** Go to [dashboard.handit.ai](https://dashboard.handit.ai) to see your AI's baseline metrics.

🛠️ **Automatic fixes:** As soon as Handit detects your first issue, it will automatically create a pull request with the fix.

**How it works:**

1. Detects quality issues in your AI responses
2. Analyzes the root cause automatically
3. Generates a fix and tests it against real data
4. Creates a pull request with the proven improvement

🔍 **Continuous monitoring:** Your AI is monitored 24/7 - when issues are detected, fixes are shipped automatically.

## Commands

### `setup` - Initial Agent Setup

Sets up Handit instrumentation for your agent.

```bash
npx @handit.ai/cli setup
```

**Options:**
- `--test` - Use test environment (localhost)

**Examples:**
```bash
# Production setup
npx @handit.ai/cli setup

# Test with localhost  
npx @handit.ai/cli setup --test
```

### `github` - GitHub Integration

Connect your repository to Handit for automatic PR creation when new prompts are detected.

```bash
npx @handit.ai/cli github
```

**What it does:**
- Authenticates with your Handit account
- Detects your Git repository
- Installs the Handit GitHub App for your repositories
- Enables automatic PR creation for prompt optimizations

**Requirements:**
- Git repository (any remote or no remote)
- GitHub account with repository access
- Handit account with company setup

### Coming Soon

The following commands are planned for future releases:

- **`monitor`** - Collect execution traces from your agent
- **`evaluate`** - Analyze traces and provide optimization insights

## Supported Languages

### JavaScript/TypeScript

**Supported Patterns:**
- Express.js route handlers
- Async/await functions
- Arrow functions
- Class methods
- Function declarations

**Example Entry Point:**
```javascript
// Express route handler
app.post('/process-document', async (req, res) => {
  const result = await processDocument(req.body);
  res.json(result);
});

// Regular function
async function processDocument(data) {
  const result = await analyzeDocument(data);
  return result;
}
```

### Python

**Supported Patterns:**
- FastAPI endpoints
- Async functions
- Class methods
- Regular functions
- Decorators

**Example Entry Point:**
```python
# FastAPI endpoint
@app.post("/process-document")
async def process_document(request: DocumentRequest):
    result = await analyze_document(request.data)
    return result

# Class method
class DocumentProcessor:
    async def process_document(self, data):
        result = await self.analyze_document(data)
        return result
```

## Configuration

### Environment Variables

```bash
# Required for AI-powered analysis
export OPENAI_API_KEY="your-openai-api-key"

# Handit.ai API key (auto-configured during setup)
export HANDIT_API_KEY="your-handit-api-key"
```

### Configuration Files

**handit.config.json** (auto-generated):
```json
{
  "agentName": "my-document-processor",
  "entryFile": "server.js",
  "entryFunction": "processDocument",
  "language": "javascript",
  "projectRoot": "/path/to/project"
}
```

## Project Structure

After setup, your project will include:

```
your-project/
├── handit.config.json          # Configuration file
├── handit_service.js           # JavaScript service (auto-generated)
├── handit_service.py           # Python service (auto-generated)
├── server.js                   # Your instrumented entry point
└── services/
    └── documentProcessor.js    # Instrumented functions
```

## Troubleshooting

### Common Issues

**❌ CLI command not found?**
Install Node.js first: `node --version` (should show v16+)

**❌ "Authentication failed" during setup?**
Check your Handit.ai account credentials at [dashboard.handit.ai](https://dashboard.handit.ai)

**❌ No traces appearing in dashboard?**
Run `handit-cli setup` again and verify your API key: `echo $HANDIT_API_KEY`

**❌ "Could not detect entry point"**
- The AI will help you find the correct entry point interactively

**❌ "No functions detected"**
- Ensure your entry function calls other functions
- Check that functions are properly exported/imported

**❌ "OpenAI API key missing"**
- Set environment variable: `export OPENAI_API_KEY="your-key"`

### Debug Mode

```bash
# Enable verbose logging
DEBUG=@handit.ai/cli:* npx @handit.ai/cli setup
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

```bash
git clone https://github.com/Handit-AI/handit-cli.git
cd handit-cli
npm install
npm run dev
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

- **Documentation**: [docs.handit.ai](https://docs.handit.ai)
- **Issues**: [GitHub Issues](https://github.com/Handit-AI/handit-cli/issues)
- **Discord**: [Join our community](https://discord.gg/handit)
- **Email**: support@handit.ai

## Acknowledgments

- Built with [OpenAI GPT-4](https://openai.com) for intelligent code analysis
- Powered by [Handit.ai](https://handit.ai) for agent monitoring
- Inspired by the need for better AI agent observability

---

**Made with ❤️ by the Handit Team**

[Website](https://handit.ai) • [Twitter](https://twitter.com/handit_ai) • [GitHub](https://github.com/Handit-AI)