npm package: @iqai/adk-cli
Description: CLI tool for creating, running, and testing ADK-TS agents
Author: IQ AI
Latest version: 0.4.8

<div align="center">
   <img src="https://files.catbox.moe/vumztw.png" alt="ADK-TS Logo" width="80" />
   <br/>
   <h1>@iqai/adk-cli</h1>
   <b>Contributing guide for the ADK-TS CLI package</b>
  <br/>
   <i>Setup • Development • Contributing • Architecture</i>

   <p align="center">
      <a href="https://www.npmjs.com/package/@iqai/adk-cli">
         <img src="https://img.shields.io/npm/v/@iqai/adk-cli" alt="NPM Version" />
      </a>
      <a href="https://www.npmjs.com/package/@iqai/adk-cli">
         <img src="https://img.shields.io/npm/dm/@iqai/adk-cli" alt="NPM Downloads" />
      </a>
      <a href="https://github.com/IQAIcom/adk-ts/blob/main/LICENSE.md">
         <img src="https://img.shields.io/npm/l/@iqai/adk-cli" alt="License" />
      </a>
      <a href="https://github.com/IQAIcom/adk-ts">
         <img src="https://img.shields.io/github/stars/IQAIcom/adk-ts?style=social" alt="GitHub Stars" />
      </a>
   </p>
</div>

---

## 📖 About

This README is specifically for contributors to the ADK-TS CLI package. The CLI provides a complete toolkit for developing, testing, and deploying AI agents with features like project scaffolding, interactive testing interfaces, and intelligent agent discovery.

If you're looking to **use** the ADK-TS CLI, visit the [live documentation](https://adk.iqai.com/docs/cli). This guide is for those who want to **contribute** to improving the CLI itself.

## 🚀 Getting Started

### Prerequisites

Before contributing to the ADK-TS CLI, ensure you have:

- [Node.js](https://nodejs.org) (version 22 or later)
- [pnpm](https://pnpm.io) (recommended package manager)
- Basic familiarity with [NestJS](https://nestjs.com/), [TypeScript](https://www.typescriptlang.org/), and CLI development

### Setting Up Development Environment

1. **Clone the repository** (if you haven't already):

   ```bash
   git clone https://github.com/IQAIcom/adk-ts.git
   cd adk-ts
   ```

2. **Install dependencies**:

   ```bash
   pnpm install
   ```

3. **Navigate to the CLI package**:

   ```bash
   cd packages/adk-cli
   ```

4. **Build the CLI**:

   ```bash
   pnpm build
   ```

5. **Link for local development**:

   ```bash
   # Link the CLI globally for testing
   npm link

   # Or run directly with pnpm
   pnpm start --help
   ```

### Development Workflow

```bash
# Watch mode for development
pnpm dev

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Type checking
pnpm type-check

# Linting
pnpm lint

# Build for production
pnpm build
```

## ⚙️ Architecture Overview

The ADK-TS CLI is built with:

- **[NestJS](https://nestjs.com)** - Modular framework for building scalable applications
- **[Commander.js](https://github.com/tj/commander.js)** - Command-line interface framework (via NestJS CLI)
- **[TypeScript](https://www.typescriptlang.org/)** - Type-safe JavaScript
- **[tsup](https://tsup.egoist.dev/)** - Fast TypeScript bundler
- **[Vitest](https://vitest.dev/)** - Fast unit testing framework

### Project Structure

```
src/
├── app.module.ts          # Main NestJS application module
├── main.ts               # CLI entry point
├── cli/                  # Command implementations
│   ├── cli.module.ts     # CLI commands module
│   ├── new.command.ts    # adk new command
│   ├── run.command.ts    # adk run command
│   ├── serve.command.ts  # adk serve command
│   └── web.command.ts    # adk web command
├── common/               # Shared utilities
│   ├── tokens.ts         # Dependency injection tokens
│   └── types.ts          # Common TypeScript types
└── http/                 # HTTP server implementation
    ├── bootstrap.ts      # Server bootstrap logic
    ├── http.module.ts    # HTTP module configuration
    ├── config/          # Configuration management
    ├── discovery/       # Agent discovery service
    ├── dto/            # Data transfer objects
    ├── events/         # Server-sent events
    ├── health/         # Health check endpoints
    ├── messaging/      # Agent messaging
    ├── providers/      # Core services
    ├── reload/         # Hot reload functionality
    ├── sessions/       # Session management
    └── state/          # State management
```

### Key Components

1. **Commands** (`src/cli/`) - Individual CLI command implementations
2. **HTTP Server** (`src/http/`) - RESTful API server for agent management
3. **Agent Discovery** (`src/http/discovery/`) - Intelligent agent scanning and loading
4. **Providers** (`src/http/providers/`) - Core services for agent management
5. **Session Management** (`src/http/sessions/`) - Conversation state persistence

## 🤝 How to Contribute

### Types of Contributions

We welcome various types of contributions to improve the CLI:

- **Add new commands** - Implement new CLI functionality
- **Improve existing commands** - Enhance current command capabilities
- **Fix bugs** - Resolve issues and improve stability
- **Add tests** - Increase test coverage and reliability
- **Improve documentation** - Update inline docs and comments
- **Optimize performance** - Make the CLI faster and more efficient
- **Add new templates** - Create project scaffolding templates

### Development Guidelines

1. **Follow TypeScript best practices** - Use proper typing and modern ES features
2. **Write comprehensive tests** - Cover new functionality with unit tests
3. **Use NestJS patterns** - Follow dependency injection and module patterns
4. **Handle errors gracefully** - Provide clear error messages and recovery
5. **Support all platforms** - Ensure compatibility across macOS, Linux, and Windows
6. **Follow semantic versioning** - Use appropriate version bumps for changes

### Testing Your Changes

1. **Unit tests**:

   ```bash
   pnpm test
   ```

2. **Manual testing with linking**:

   ```bash
   # Build and link for testing
   pnpm build
   npm link

   # Test commands
   adk --help
   adk new test-project
   ```

3. **Integration testing**:

   ```bash
   # Test with actual agent projects
   cd /tmp
   adk new test-agent --template simple-agent
   cd test-agent
   adk run
   ```

### Contribution Workflow

1. **Fork the repository** on GitHub
2. **Create a feature branch** from main:

   ```bash
   git checkout -b cli/add-new-feature
   ```

3. **Make your changes** following the guidelines above
4. **Add or update tests** for your changes
5. **Run the test suite** to ensure nothing breaks:

   ```bash
   pnpm test
   pnpm type-check
   pnpm lint
   ```

6. **Test manually** by linking and running CLI commands
7. **Commit your changes** with descriptive commit messages:

   ```bash
   git commit -m "cli: add support for custom agent templates"
   ```

8. **Push to your fork** and **create a Pull Request**

### Adding New Commands

To add a new CLI command:

1. **Create command file** in `src/cli/`:

   ```typescript
   // src/cli/my-command.ts
   import { Command, CommandRunner } from "nest-commander";

   @Command({
     name: "my-command",
     description: "Description of what the command does",
   })
   export class MyCommand extends CommandRunner {
     async run(passedParams: string[]): Promise<void> {
       // Implementation here
     }
   }
   ```

2. **Register in CLI module**:

   ```typescript
   // src/cli/cli.module.ts
   import { MyCommand } from "./my-command";

   @Module({
     providers: [
       // ... other commands
       MyCommand,
     ],
   })
   export class CliModule {}
   ```

3. **Add tests**:

   ```typescript
   // src/cli/my-command.spec.ts
   describe("MyCommand", () => {
     // Test implementation
   });
   ```

### Working with the HTTP Server

The CLI includes a full HTTP server for agent management. Key areas:

- **Controllers** - Handle HTTP requests (`src/http/*/`)
- **Services** - Business logic implementation
- **DTOs** - Request/response data structures
- **Modules** - NestJS module organization

## 🧪 Testing

### Running Tests

```bash
# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

# Run specific test file
pnpm test my-command.spec.ts
```

### Test Structure

Tests are organized alongside source files:

- Unit tests: `*.spec.ts`
- Integration tests: `*.integration.spec.ts`
- E2E tests: `*.e2e.spec.ts`

## 📚 Resources for Contributors

### ADK-TS Framework Resources

- **[ADK-TS Repository](https://github.com/IQAIcom/adk-ts)** - Main framework repository
- **[Live Documentation](https://adk.iqai.com)** - Published documentation site
- **[CLI Documentation](https://adk.iqai.com/docs/cli)** - User-facing CLI docs
- **[Contributing Guide](../../CONTRIBUTION.md)** - General project contribution guidelines
- **[Examples](../../apps/examples/)** - Code examples and tutorials

### Technical Resources

- **[NestJS Documentation](https://docs.nestjs.com)** - Framework powering the CLI
- **[Commander.js](https://github.com/tj/commander.js)** - CLI framework patterns
- **[TypeScript Handbook](https://www.typescriptlang.org/docs/)** - TypeScript best practices
- **[Vitest Documentation](https://vitest.dev/)** - Testing framework guide

### Development Tools

- **[tsup Configuration](./tsup.config.ts)** - Build configuration
- **[Vitest Configuration](./vitest.config.ts)** - Test configuration
- **[TypeScript Configuration](./tsconfig.json)** - Type checking setup
- **[HTTP Layer Architecture](./src/http/ARCHITECTURE.md)** - Technical documentation for the HTTP server layer

## 🔧 Debugging

When working on the CLI codebase, use these debugging techniques:

```bash
# Enable detailed logging for development
export ADK_DEBUG=true
export ADK_VERBOSE=true

# Test your changes with verbose output
adk run --verbose
adk serve --verbose
```

### Common Contributor Issues

1. **Module resolution errors** - Ensure proper imports and module registration in NestJS
2. **Build failures** - Check TypeScript configuration and dependency versions
3. **Test failures** - Verify mock setups and async handling in test files
4. **Runtime errors during development** - Use debug logging and proper error handling

---

**Ready to contribute?** Start by exploring the codebase, running the tests, and trying out the existing commands. Your contributions help make the ADK-TS CLI more powerful and user-friendly for developers worldwide!