adk-ts/packages/adk-cli

@iqai/adk-cli

Contributing guide for the ADK-TS CLI package
Setup • Development • Contributing • Architecture

---

📖 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. 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 (version 22 or later)
• pnpm (recommended package manager)
• Basic familiarity with NestJS, TypeScript, and CLI development

Setting Up Development Environment

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

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

2. Install dependencies:

   pnpm install
   

3. Navigate to the CLI package:

   cd packages/adk-cli
   

4. Build the CLI:

   pnpm build
   

5. Link for local development:

   # Link the CLI globally for testing
   npm link
   
   # Or run directly with pnpm
   pnpm start --help
   

Development Workflow

# 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 - Modular framework for building scalable applications
• Commander.js - Command-line interface framework (via NestJS CLI)
• TypeScript - Type-safe JavaScript
• tsup - Fast TypeScript bundler
• Vitest - 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:

   pnpm test
   

2. Manual testing with linking:

   # Build and link for testing
   pnpm build
   npm link
   
   # Test commands
   adk --help
   adk new test-project
   

3. Integration testing:

   # 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:

   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:

   pnpm test
   pnpm type-check
   pnpm lint
   

6. Test manually by linking and running CLI commands

7. Commit your changes with descriptive commit messages:

   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/:

   // 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:

   // src/cli/cli.module.ts
   import { MyCommand } from "./my-command";
   
   @Module({
     providers: [
       // ... other commands
       MyCommand,
     ],
   })
   export class CliModule {}
   

3. Add tests:

   // 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

# 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 - Main framework repository
• Live Documentation - Published documentation site
• CLI Documentation - User-facing CLI docs
• Contributing Guide - General project contribution guidelines
• Examples - Code examples and tutorials

Technical Resources

• NestJS Documentation - Framework powering the CLI
• Commander.js - CLI framework patterns
• TypeScript Handbook - TypeScript best practices
• Vitest Documentation - Testing framework guide

Development Tools

• tsup Configuration - Build configuration
• Vitest Configuration - Test configuration
• TypeScript Configuration - Type checking setup
• HTTP Layer Architecture - Technical documentation for the HTTP server layer

🔧 Debugging

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

# 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!