---
description: Comprehensive CLI development documentation hub for the Anyscale CLI and SDK
globs:
  - frontend/cli/**/*
alwaysApply: false
---

# Anyscale CLI Documentation

This directory contains comprehensive documentation for developing, testing, and maintaining the Anyscale CLI and SDK.

## 📚 Documentation Structure

### Core References

#### [rules.mdc](./rules.mdc) ⭐ **Always Active**
Quick reference and task mapping for CLI development
- Essential commands and patterns
- Task-to-documentation mapping
- Core principles and common mistakes
- **Always loaded** for immediate reference

#### [architecture.mdc](./architecture.mdc)
System design and component interactions
- Layered architecture (CLI → SDK → Client → API)
- Directory structure
- Data flow patterns
- Component responsibilities

### Development Workflow

#### [workflow-simple.mdc](./workflow-simple.mdc)
Step-by-step guide for adding features
- Quick development workflow
- Adding new features checklist
- Testing and deployment steps

#### [development.mdc](./development.mdc)
Detailed development patterns
- SDK implementation patterns
- CLI command structure
- Model definitions
- Auto-attaches when working with commands

#### [api-client.mdc](./api-client.mdc)
OpenAPI client integration
- Client generation process
- Adding new endpoints
- Error handling patterns
- Auto-attaches for client code

### Code Quality

#### [style-guide.mdc](./style-guide.mdc)
Python conventions and standards
- Naming conventions
- Import organization
- Documentation standards
- Auto-attaches for all Python files

#### [testing.mdc](./testing.mdc)
Testing patterns and commands
- Unit test structure
- Mock patterns
- Test organization
- Auto-attaches for test files

#### [testing-guide.mdc](./testing-guide.mdc)
Practical testing workflow
- Local development setup
- Running and debugging tests
- Common test patterns

### Features & Patterns

#### [authentication.mdc](./authentication.mdc)
Auth flow and credential management
- Token storage
- Security rules
- Testing auth
- Auto-attaches for auth-related code

#### [error-handling.mdc](./error-handling.mdc)
Exception handling and user messages
- Error hierarchy
- User-friendly messages
- Validation patterns
- Auto-attaches for all Python files

#### [telemetry.mdc](./telemetry.mdc)
Usage tracking and privacy
- Event collection
- Privacy rules
- Custom events
- Auto-attaches for command files

#### [cloud-providers.mdc](./cloud-providers.mdc)
Cloud abstraction patterns
- AWS, GCP, Azure support
- Cloud configuration
- Provider-specific features
- Auto-attaches for cloud-related code

## 🚀 Quick Start

### New to CLI Development?
1. Start with [rules.mdc](./rules.mdc) for overview
2. Review [architecture.mdc](./architecture.mdc) to understand the system
3. Follow [workflow-simple.mdc](./workflow-simple.mdc) for your first feature

### Adding a Feature
1. Check task mapping in [rules.mdc](./rules.mdc)
2. Follow workflow in [workflow-simple.mdc](./workflow-simple.mdc)
3. Reference [development.mdc](./development.mdc) for patterns
4. Write tests using [testing.mdc](./testing.mdc)

### Debugging Issues
- Auth problems → [authentication.mdc](./authentication.mdc)
- API errors → [error-handling.mdc](./error-handling.mdc)
- Client generation → [api-client.mdc](./api-client.mdc)
- Cloud issues → [cloud-providers.mdc](./cloud-providers.mdc)

## 🔑 Key Commands

```bash
# Install CLI for development
cd frontend/cli && pip install -e .

# Run all tests
bazelisk test //frontend/cli/tests/unit/... --test_output=all

# Regenerate API clients
cd frontend/web && npm run build-api

# Debug mode
export ANYSCALE_DEBUG=1

# Check auth
anyscale auth show
```

## 📋 Rule Configuration

All documentation files follow [Cursor's rule best practices](https://docs.cursor.com/en/context/rules#rule-anatomy):

| Rule | Type | When Applied |
|------|------|-------------|
| **rules.mdc** | Always Active | Constant reference for commands and patterns |
| **architecture.mdc** | Auto-attach | When working with system design |
| **style-guide.mdc** | Auto-attach | All Python files |
| **testing.mdc** | Auto-attach | Test files |
| **authentication.mdc** | Auto-attach | Auth-related code |
| **error-handling.mdc** | Auto-attach | Python implementation files |
| **api-client.mdc** | Auto-attach | Client/OpenAPI code |
| Others | Manual/Context | As needed or AI-requested |

## 🏗️ CLI Architecture Overview

```
User Input
    ↓
CLI Layer (Click)           # User interface, argument parsing
    ↓
SDK Layer                   # Business logic, orchestration
    ↓
AnyscaleClient Wrapper      # Auth, error normalization
    ↓
OpenAPI Generated Clients   # Auto-generated from FastAPI
    ↓
Backend API                 # FastAPI services
```

## 🤝 Contributing

When updating documentation:
1. Follow MDC format with proper metadata headers
2. Keep files under 500 lines
3. Include practical examples
4. Update this README if adding new files
5. Test all code examples before committing

## 💡 Tips

- **SDK-first**: Always implement in SDK, wrap in CLI
- **Type everything**: Full type hints required
- **Never edit generated code**: Regenerate from OpenAPI specs
- **Test both layers**: SDK and CLI need separate tests
- **Clear errors**: No stack traces to users

## 📊 Development Metrics

- **Files**: 12 comprehensive guides
- **Coverage**: Architecture, development, testing, deployment
- **Auto-attachment**: Smart context loading based on file patterns
- **Always Available**: Quick reference via rules.mdc
