npm package: @kairoaisec/cli
Description: Kairo CLI for smart contract security scanning
Author: Kairo
Latest version: 0.1.9

# Kairo CLI

The official command-line interface for Kairo, the AI-powered smart contract security platform.

## Installation

```bash
npm install -g @kairoaisec/cli
```

## Quick Start

1. **Login to your Kairo account:**

   ```bash
   kairo auth login
   ```

2. **Create or select a project:**

   ```bash
   kairo project create my-project
   kairo project select my-project
   ```

3. **Scan your contracts:**
   ```bash
   kairo scan ./contracts
   ```

## Commands

### Authentication

- `kairo auth login` - Login to your Kairo account
- `kairo auth logout` - Logout from your account
- `kairo auth whoami` - Show current user information

### Project Management

- `kairo project create <name>` - Create a new project
- `kairo project list` - List all projects
- `kairo project select <name>` - Select active project

### Security Scanning

- `kairo scan [path]` - Scan contracts for vulnerabilities (uses full 6-stage ML pipeline)
- `kairo scan [path] --format json` - Output results as JSON to stdout
- `kairo scan [path] --format sarif` - Output results as SARIF to stdout
- `kairo scan [path] --no-upload` - Scan locally without uploading to dashboard
- `kairo scan [path] --no-slither` - Skip Slither, use Kairo patterns only
- `kairo scan [path] --slither-only` - Run only Slither analysis
- `kairo scan [path] --fail-on critical,high` - Exit with code 1 if findings match severity

### Configuration

- `kairo config get [key]` - View configuration
- `kairo config set <key> <value>` - Set configuration value
- `kairo config reset` - Reset configuration
- `kairo config path` - Show config file location

## Scanning

All scans use the full 6-stage ML security pipeline for maximum accuracy:

1. **Pattern matching** - 50+ vulnerability patterns (reentrancy, access control, overflow, DeFi-specific, etc.)
2. **AST analysis** - Structural code analysis
3. **Solidity version awareness** - Suppresses false positives for >=0.8.0
4. **ReentrancyGuard detection** - Recognizes common protection patterns
5. **Context-aware analysis** - tx.origin, access control patterns
6. **ML pipeline** - CodeBERT + Claude AI analysis (when authenticated)

```bash
kairo scan ./contracts
```

> **Note:** Authenticated scans include the full ML pipeline. Your code is processed securely via the Kairo API. Unauthenticated scans fall back to local pattern matching.

### Output Formats

Both modes support structured output to stdout for piping:

```bash
# JSON output, pipe to jq
kairo scan ./contracts --format json | jq '.findings[] | select(.severity == "critical")'

# SARIF output for GitHub Code Scanning
kairo scan ./contracts --format sarif > results.sarif
```

## Examples

### Basic Workflow

```bash
# Login
kairo auth login

# Create a project
kairo project create defi-protocol --description "My DeFi protocol"

# Select the project
kairo project select defi-protocol

# Check status
kairo whoami

# Scan contracts
kairo scan ./contracts
```

### API Key Authentication

```bash
# Login with API key instead of OAuth
kairo auth login --api-key kairo_sk_live_your_api_key_here

# Or use environment variable (recommended for CI/CD)
export KAIRO_API_KEY=kairo_sk_live_your_api_key_here
kairo scan ./contracts

# Generate API keys at: https://kairoaisec.com/client/projects
```

### Configuration Management

```bash
# View all configuration
kairo config get

# Set custom API URL
kairo config set apiUrl https://api.kairoaisec.com

# Reset everything
kairo config reset
```

## Configuration

Configuration is stored securely using:

- **Keychain/Credential Manager** - For sensitive tokens
- **Local config file** - For non-sensitive settings

Default API URL: `https://kairoaisec.com`

## Roadmap

This CLI is part of Kairo's strategic pivot to enterprise CLI + Dashboard. Current status:

### ✅ Phase 0: Foundation (Complete)

- [x] Authentication system
- [x] Project management
- [x] API client integration
- [x] Configuration management

### ✅ Phase 0: Scanning (Complete)

- [x] Full 6-stage ML security pipeline (pattern + ML analysis)
- [x] Slither integration
- [x] Findings upload to dashboard
- [x] Progress indicators
- [x] JSON and SARIF output formats (stdout-friendly for piping)
- [x] False positive reduction (ReentrancyGuard, tx.origin context, Solidity >=0.8.0)
- [x] API key authentication (kairo*sk_live*\* format)
- [x] 50+ vulnerability patterns

### 🔮 Phase 1: CI/CD Integration

- [ ] GitHub Actions integration
- [ ] PR annotations
- [ ] Deployment gates

### 🔮 Phase 2: Advanced Features

- [ ] Mythril integration
- [ ] AI chat in terminal
- [ ] Custom rules

## Development

```bash
# Clone the repo
git clone https://github.com/kairoaisec/kairo.git
cd kairo/packages/cli

# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev

# Test locally
npm link
kairo --help
```

## Support

- 📚 [Documentation](https://docs.kairoaisec.com)
- 🐛 [Report Issues](https://github.com/kairoaisec/kairo/issues)
- 💬 [Discord Community](https://discord.gg/kairo)

## License

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