# CLI Reference

## Global Options

### `paxx --version`

Show the paxx version and exit.

```bash
paxx --version
paxx -v
```

---

## Project Commands

### `paxx bootstrap`

Create a new paxx project with the standard structure.

```bash
paxx bootstrap <name> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `name` | Name of the new project (required) |

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `-o, --output-dir PATH` | Directory to create the project in | Current directory |
| `-d, --description TEXT` | Project description | - |
| `-a, --author TEXT` | Author name | "Author" |

**Examples:**

```bash
paxx bootstrap myproject
paxx bootstrap my-api --description "My awesome API"
paxx bootstrap myproject -o /path/to/projects
```

---

### `paxx start`

Start the development server (uvicorn wrapper).

```bash
paxx start [OPTIONS]
```

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `-h, --host TEXT` | Host to bind to | 127.0.0.1 |
| `-p, --port INTEGER` | Port to bind to | 8000 |
| `-r, --reload / -R, --no-reload` | Enable auto-reload | Enabled |
| `-w, --workers INTEGER` | Number of workers (only without reload) | 1 |

**Examples:**

```bash
paxx start                         # Start on localhost:8000 with reload
paxx start --port 3000             # Start on port 3000
paxx start --host 0.0.0.0          # Bind to all interfaces
paxx start --no-reload --workers 4 # Production-like mode
```

---

## Feature Commands

### `paxx feature create`

Create a new domain feature from scratch.

```bash
paxx feature create <name> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `name` | Name of the new feature (required) |

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `-d, --description TEXT` | Feature description | - |

**Examples:**

```bash
paxx feature create users
paxx feature create blog_posts
paxx feature create orders --description "Order management"
```

**Generated Structure:**

```
features/<name>/
├── __init__.py
├── config.py      # Feature configuration (prefix, tags)
├── models.py      # SQLAlchemy models
├── schemas.py     # Pydantic schemas
├── services.py    # Business logic
└── routes.py      # API endpoints
```

---

### `paxx feature add`

Add a bundled feature to your project.

```bash
paxx feature add <feature> [OPTIONS]
paxx feature add --list
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `feature` | Name of the bundled feature to add |

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `-l, --list` | List all available features | - |
| `-f, --force` | Overwrite existing feature | False |

**Examples:**

```bash
paxx feature add --list            # List available features
paxx feature add example_products  # Add the example CRUD feature
paxx feature add auth --force      # Overwrite existing auth feature
```

!!! note "Feature Ownership"
    Once a feature is added, you own the code. Customize it freely for your needs.

---

## Database Commands

All database commands are thin wrappers around Alembic.

### `paxx db migrate`

Create a new database migration.

```bash
paxx db migrate <message> [OPTIONS]
```

**Arguments:**

| Argument | Description |
|----------|-------------|
| `message` | Migration message describing the changes (required) |

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `-a, --autogenerate / -A, --no-autogenerate` | Auto-detect model changes | Enabled |

**Examples:**

```bash
paxx db migrate "add users table"
paxx db migrate "add email index" --no-autogenerate
```

---

### `paxx db upgrade`

Apply migrations to the database.

```bash
paxx db upgrade [REVISION]
```

**Arguments:**

| Argument | Description | Default |
|----------|-------------|---------|
| `revision` | Target revision | head (latest) |

**Examples:**

```bash
paxx db upgrade          # Apply all pending migrations
paxx db upgrade head     # Same as above
paxx db upgrade +1       # Apply next migration only
paxx db upgrade abc123   # Migrate to specific revision
```

---

### `paxx db downgrade`

Revert migrations.

```bash
paxx db downgrade [REVISION]
```

**Arguments:**

| Argument | Description | Default |
|----------|-------------|---------|
| `revision` | Target revision | -1 (previous) |

**Examples:**

```bash
paxx db downgrade        # Revert last migration
paxx db downgrade -1     # Same as above
paxx db downgrade -2     # Revert last 2 migrations
paxx db downgrade base   # Revert all migrations
paxx db downgrade abc123 # Downgrade to specific revision
```

---

### `paxx db status`

Show current migration status.

```bash
paxx db status
```

---

### `paxx db history`

Show migration history.

```bash
paxx db history [OPTIONS]
```

**Options:**

| Option | Description |
|--------|-------------|
| `-v, --verbose` | Show detailed history |

---

### `paxx db heads`

Show current available heads (useful for migration branches).

```bash
paxx db heads
```
