npm package: @kyraak/cli
Description: CLI tool for building and deploying AI agents on Kyraak
Author: Prayag Dave
Latest version: 0.1.0

# @kyraak/cli

**Command-line tool for building and deploying AI agents on Kyraak**

The fastest way to go from idea to deployed AI agent.

---

## Installation

```bash
# Global install (recommended)
npm install -g @kyraak/cli

# Or use with npx (no install needed)
npx @kyraak/cli init my-agent
```

---

## Quick Start

### 1. Create a New Agent

```bash
kyraak init my-agent
cd my-agent
npm install
```

### 2. Run Locally

```bash
kyraak dev
```

### 3. Deploy to Kyraak

```bash
kyraak deploy
```

That's it! Your agent is now live on the Kyraak platform. ✅

---

## Commands

### `kyraak init [name]`

Initialize a new agent project.

**Options:**
- `-t, --template <template>` - Template to use (default: `hello-world`)
  - `hello-world` - Simple greeting agent
  - `trend-analyzer` - Advanced agent with lifecycle hooks
- `--typescript` - Use TypeScript (default)
- `--javascript` - Use JavaScript

**Examples:**

```bash
# Create agent with prompts
kyraak init

# Create agent with name
kyraak init my-agent

# Use specific template
kyraak init my-agent --template trend-analyzer

# Use JavaScript instead of TypeScript
kyraak init my-agent --javascript
```

**What it creates:**

```
my-agent/
├── src/
│   └── index.ts          # Agent code
├── package.json          # Dependencies
├── tsconfig.json         # TypeScript config
├── .gitignore           # Git ignore rules
└── README.md            # Documentation
```

---

### `kyraak dev`

Run agent locally with hot reload.

**Options:**
- `-p, --port <port>` - Port to run on (default: `3000`)
- `--watch` - Enable hot reload (default: `true`)
- `--no-watch` - Disable hot reload

**Examples:**

```bash
# Run on default port (3000)
kyraak dev

# Run on custom port
kyraak dev --port 8080

# Disable hot reload
kyraak dev --no-watch
```

**What it does:**
1. Loads your agent code
2. Runs a test invocation
3. Watches for file changes (TypeScript only)
4. Shows output in real-time

**Output:**

```
🔧 Kyraak Development Server

Agent: my-agent
Port: 3000
Watch: enabled
Language: TypeScript

✓ Agent loaded successfully

➜ Local: http://localhost:3000

Testing agent...

Input: { id: 'dev-test', params: { name: 'Kyraak' } }

Output: {
  success: true,
  data: { greeting: 'Hello, Kyraak!' },
  metadata: { duration: 2 }
}

✓ Test passed
```

---

### `kyraak deploy`

Deploy agent to Kyraak platform.

**Options:**
- `--prod` - Deploy to production
- `--preview` - Deploy to preview environment (default)
- `--no-build` - Skip build step

**Examples:**

```bash
# Deploy to preview
kyraak deploy

# Deploy to production
kyraak deploy --prod

# Deploy without rebuilding
kyraak deploy --no-build
```

**What it does:**
1. Builds your agent (if TypeScript)
2. Packages the code
3. Uploads to Kyraak infrastructure
4. Deploys to edge network globally
5. Generates deployment URL

**Output:**

```
🚀 Kyraak Deploy

Agent: my-agent
Version: 1.0.0
Environment: production

Building agent...
✓ Build complete

✓ Deployment successful!

Deployment Details:
  URL: https://my-agent.kyraak.app
  Environment: production
  Region: Global (Edge)
  Status: Ready

Next Steps:
  • View dashboard: https://kyraak.dev/dashboard/my-agent
  • Monitor logs: https://kyraak.dev/logs/abc123
  • View analytics: https://kyraak.dev/analytics/my-agent
```

---

## Templates

### hello-world

Simple agent that returns a greeting.

**Best for:**
- Learning Kyraak
- Quick prototypes
- Simple use cases

**Code:**

```typescript
import { Agent } from '@kyraak/sdk';

const agent = new Agent({
  config: {
    name: 'hello-world',
    description: 'A simple greeting agent',
  },

  execute: async (input) => {
    const name = input.params.name || 'World';
    return { greeting: `Hello, ${name}!` };
  },
});

export default agent;
```

---

### trend-analyzer

Advanced agent with lifecycle hooks.

**Best for:**
- Production agents
- Agents with setup/cleanup
- Complex business logic

**Code:**

```typescript
import { Agent } from '@kyraak/sdk';

let database: any;

const agent = new Agent({
  config: {
    name: 'trend-analyzer',
    description: 'Analyzes social media trends',
    timeout: 5000,
  },

  // Load data once
  init: async (context) => {
    context.utils.log('Loading database...', 'info');
    database = await loadDatabase();
  },

  // Process requests
  execute: async (input, context) => {
    const { keyword } = input.params;
    const score = database.get(keyword);
    return { keyword, score };
  },

  // Cleanup resources
  cleanup: async (context) => {
    await database.close();
  },
});

export default agent;
```

---

## Project Structure

### TypeScript Project

```
my-agent/
├── src/
│   └── index.ts          # Agent code (edit this)
├── dist/                 # Compiled output (auto-generated)
├── node_modules/         # Dependencies
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md
```

### JavaScript Project

```
my-agent/
├── index.js              # Agent code (edit this)
├── node_modules/         # Dependencies
├── package.json
├── .gitignore
└── README.md
```

---

## Workflow

### Development Workflow

```bash
# 1. Create agent
kyraak init my-agent
cd my-agent

# 2. Install dependencies
npm install

# 3. Edit code
# Open src/index.ts and write your agent logic

# 4. Test locally
kyraak dev

# 5. Deploy to preview
kyraak deploy

# 6. Test in preview environment
# Visit https://my-agent-abc123.kyraak.app

# 7. Deploy to production
kyraak deploy --prod

# 8. Share with users
# Your agent is live at https://my-agent.kyraak.app
```

### Continuous Deployment

```bash
# In your CI/CD pipeline (GitHub Actions, etc.)

- name: Deploy to Kyraak
  run: |
    npm install -g @kyraak/cli
    kyraak deploy --prod
  env:
    KYRAAK_TOKEN: ${{ secrets.KYRAAK_TOKEN }}
```

---

## Best Practices

### 1. Use TypeScript

TypeScript catches bugs before deployment:

```bash
kyraak init my-agent --typescript  # Default
```

### 2. Test Locally First

Always test with `kyraak dev` before deploying:

```bash
kyraak dev  # Test changes
kyraak deploy --preview  # Deploy to preview
kyraak deploy --prod  # Deploy to production
```

### 3. Use Templates

Start with a template and modify:

```bash
kyraak init my-agent --template trend-analyzer
```

### 4. Version Your Agents

Update `package.json` version before deploying:

```json
{
  "name": "my-agent",
  "version": "1.0.1"  // Increment this
}
```

### 5. Monitor Deployments

Check dashboard after deploying:

```
https://kyraak.dev/dashboard/my-agent
```

---

## Troubleshooting

### "Not a Kyraak project"

Make sure you're in a directory with `package.json` and `@kyraak/sdk` installed:

```bash
npm install @kyraak/sdk
```

### Build Errors

Clear dist and rebuild:

```bash
rm -rf dist
npm run build
```

### Deployment Fails

Check your agent works locally first:

```bash
kyraak dev
```

---

## Environment Variables

### Local Development

Create `.env.local` file:

```
API_KEY=your-api-key
DATABASE_URL=your-database-url
```

Access in agent:

```typescript
const apiKey = process.env.API_KEY;
```

### Production

Set environment variables in Kyraak dashboard:

```
https://kyraak.dev/dashboard/my-agent/settings
```

---

## Help

### Get Help

```bash
kyraak --help
kyraak init --help
kyraak dev --help
kyraak deploy --help
```

### Version

```bash
kyraak --version
```

---

## Examples

### Simple Calculator Agent

```bash
kyraak init calculator
cd calculator
```

Edit `src/index.ts`:

```typescript
import { Agent } from '@kyraak/sdk';

const agent = new Agent({
  config: { name: 'calculator' },

  execute: async (input) => {
    const { a, b, operation } = input.params;
    
    const operations: Record<string, number> = {
      add: a + b,
      subtract: a - b,
      multiply: a * b,
      divide: a / b,
    };
    
    return { result: operations[operation] };
  },
});

export default agent;
```

Test and deploy:

```bash
kyraak dev
kyraak deploy --prod
```

---

## Links

- [Documentation](https://kyraak.dev/docs)
- [SDK Reference](https://kyraak.dev/docs/sdk)
- [CLI Reference](https://kyraak.dev/docs/cli)
- [Examples](https://kyraak.dev/examples)
- [GitHub](https://github.com/prayagdave25/kyraak-platform)

---

## License

MIT License - See [LICENSE](../../LICENSE) for details.

---

**Built with 🔥 by [Prayag Dave](https://twitter.com/prayagdave)**