buildx-cli/README.md

CLI tool for BuildX API with authentication and schema synchronization

# BuildX CLI

A command-line interface tool for BuildX API with authentication, project management, and schema synchronization capabilities.

## Features

- **🔐 Authentication Management**: Secure login/logout with token validation
- **📁 Project Management**: List, set default, and manage multiple projects
- **🔄 Schema Synchronization**: Generate TypeScript types from API schema
- **⚙️ Configuration Management**: Store settings or use environment variables
- **🎯 Interactive CLI**: User-friendly command-line interface with prompts

## Installation

### Using npx (Recommended)
```bash
npx buildx-cli --help
```

### Global Installation
```bash
npm install -g buildx-cli
```

### Local Development
```bash
git clone <repository-url>
cd buildx-cli
yarn install
yarn build
yarn start --help
```

## Quick Start

1. **Configure API settings:**
   ```bash
   npx buildx-cli config:setup
   ```

2. **Authenticate:**
   ```bash
   npx buildx-cli auth:login
   ```

3. **List projects:**
   ```bash
   npx buildx-cli projects:list
   ```

4. **Sync schema:**
   ```bash
   npx buildx-cli schema:sync --project-id <project-id>
   ```

## Configuration

### Method 1: Interactive Setup
```bash
npx buildx-cli config:setup
```

### Method 2: Environment Variables
Set these environment variables or add them to a `.env` file:

```bash
BUILDX_API_ENDPOINT=https://api.example.com
BUILDX_API_KEY=your-api-key
BUILDX_PROJECT_ID=your-default-project-id
```

### Method 3: Command Line Options
```bash
npx buildx-cli config:setup --endpoint https://api.example.com --api-key your-api-key
```

### View Current Configuration
```bash
npx buildx-cli config:show
```

### Clear Configuration
```bash
npx buildx-cli config:clear
```

## Commands

### Authentication Commands

#### Login
```bash
npx buildx-cli auth:login
```
Interactive login with username/password or token.

#### Logout
```bash
npx buildx-cli auth:logout
```
Clear stored authentication.

#### Check Status
```bash
npx buildx-cli auth:status
```
Display authentication status and user information.

### Project Management Commands

#### List Projects
```bash
npx buildx-cli projects:list
```
Display all available projects.

#### Set Default Project
```bash
npx buildx-cli projects:set-default <project-id>
```
Set the default project for operations.

#### Show Current Project
```bash
npx buildx-cli projects:current
```
Display the currently selected default project.

### Schema Synchronization Commands

#### Sync Schema
```bash
npx buildx-cli schema:sync --project-id <project-id>
```

#### Sync with Custom Output
```bash
npx buildx-cli schema:sync --project-id <project-id> --output ./src/types/generated.ts
```

#### Sync with Custom API URL
```bash
npx buildx-cli schema:sync --project-id <project-id> --api-url https://custom-api.example.com
```

### Configuration Commands

#### Setup Configuration
```bash
npx buildx-cli config:setup
```
Interactive configuration setup.

#### Show Configuration
```bash
npx buildx-cli config:show
```
Display current configuration and sources.

#### Clear Configuration
```bash
npx buildx-cli config:clear
```
Clear all stored configuration.

## Configuration Sources

The CLI checks for configuration in this order:

1. **Stored Configuration** (via `config:setup`)
2. **Environment Variables** (`BUILDX_API_ENDPOINT`, `BUILDX_API_KEY`)
3. **`.env` File** (in current directory)

### Configuration File Location
- **Global config**: `~/.config/buildx-cli-nodejs/config.json`

### Environment Variables
- `BUILDX_API_ENDPOINT` - Your API endpoint URL
- `BUILDX_API_KEY` - Your API key
- `BUILDX_PROJECT_ID` - Default project ID (optional)

## API Endpoints

The CLI interacts with the following API endpoints:

- `POST /auth/login` - User authentication
- `GET /auth/me` - Get current user info
- `GET /projects` - List user projects
- `GET /project/:project_id/collections/schema` - Fetch project schema

## Development

### Project Structure

```
src/
├── commands/          # CLI commands
│   ├── auth/         # Authentication commands
│   ├── config/       # Configuration commands
│   ├── projects/     # Project management commands
│   └── sync.ts       # Schema synchronization
├── services/          # Business logic services
├── types/            # TypeScript type definitions
├── utils/            # Utility functions
├── config/           # Configuration management
└── index.ts          # Main entry point
```

### Available Scripts

```bash
yarn build          # Build the project
yarn dev            # Run in development mode
yarn start          # Run built version
yarn test           # Run tests
yarn lint           # Run linter
yarn format         # Format code
```

### Building

```bash
yarn build
```

### Development Mode

```bash
yarn dev
```

## Examples

### CI/CD Pipeline
```bash
# Set environment variables
export BUILDX_API_ENDPOINT=https://api.example.com
export BUILDX_API_KEY=$CI_API_KEY
export BUILDX_PROJECT_ID=$CI_PROJECT_ID

# Run schema sync
npx buildx-cli schema:sync --project-id $BUILDX_PROJECT_ID --output ./src/types/api.ts
```

### Local Development
```bash
# Setup once
npx buildx-cli config:setup

# Use regularly
npx buildx-cli projects:list
npx buildx-cli schema:sync --project-id my-project
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

## License

MIT License - see LICENSE file for details.