Metadata-Version: 2.4
Name: backant-cli
Version: 0.7.3
Summary: A CLI tool to generate backant backend projects
Home-page: https://github.com/backant/backant-cli
Author: Pavel Hegler
Author-email: business@hegler.tech
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: click
Requires-Dist: pydantic>=2.0
Requires-Dist: posthog>=3.0.0
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Backant CLI

Backant CLI is a powerful Linux native command-line interface designed to streamline the development of Flask-based REST APIs. It automates the generation of a complete and scalable project structure, allowing developers to focus on business logic rather than boilerplate code.

## Key Features

- **Automated Project Scaffolding**: Generate a new Flask API with a single command, including a well-organized directory structure.
- **Layered Architecture**: The generated project follows a clean, layered architecture (Models, Repositories, Services, Routes) to promote separation of concerns and maintainability.
- **Database-Ready**: Includes SQLAlchemy for database modeling and interaction, with a pre-configured `DBSession` for easy database access.
- **Dockerized Environment**: Comes with `Dockerfile` and `docker-compose.yml` files for a consistent development and production environment.
- **Extensible by Design**: Easily add new routes, services, and models using the provided CLI commands.
- **Pre-configured for Deployment**: Includes a GitHub Actions workflow for building and pushing Docker images to Amazon ECR.

## Installation

### Ubuntu/Debian (Recommended)

Install the Backant CLI using the .deb package for Ubuntu/Debian systems:

```bash
# Download and install the .deb package
sudo dpkg -i backant-cli.deb
```

### Alternative: Python Package

You can also install using pip:

```bash
pip install backant-cli
```

## Getting Started

### Generating a New API

To create a new Flask API project, use the `generate api` command:

```bash
ant generate api <your_project_name>
```

This will create a new directory named `<your_project_name>` with the complete project structure.

### Generating API from JSON Specification

You can generate a complete API with routes and subroutes from a JSON specification using the `--json` option:

#### Using JSON String:
```bash
ant generate api my-project --json '{"routes": {"products": {"type": "GET", "subroutes": {"create": {"type": "POST"}}}}}'
```

#### Using JSON File:
```bash
ant generate api ecommerce --json api-spec.json
```

#### Additional Options:
- `--verbose` or `-v`: Show detailed generation progress
- `--dry-run`: Validate JSON specification without generating files

#### Examples:
```bash
# Generate API with verbose output
ant generate api shop --json api-spec.json --verbose

# Validate JSON specification without creating files
ant generate api test --json api.json --dry-run
```

#### JSON Specification Format:
The JSON specification should follow this structure:
```json
{
  "routes": {
    "route_name": {
      "type": "GET|POST|PUT|DELETE",
      "mock": {},
      "subroutes": {
        "subroute_name": {
          "type": "GET|POST|PUT|DELETE",
          "mock": {}
        }
      }
    }
  }
}
```

### Generating a New Route

Once you have a project, you can easily add new routes and their corresponding components (service, repository, model) with the `generate route` command:

```bash
ant generate route <your_route_name>
```

This command will automatically create:
- A new route in `api/routes/`
- A new service in `api/services/`
- A new repository in `api/repositories/`
- A new model in `api/models/`

### Generating a Mock Route

You can also generate a route with mock data for testing and development purposes. Use the `--mock` option with a JSON string or a path to a JSON file.

#### Using a JSON String:

```bash
ant generate route <your_route_name> --mock '{"key": "value", "another_key": "another_value"}'
```

#### Using a JSON File:

```bash
ant generate route <your_route_name> --mock /path/to/your/mock_data.json
```

This will generate the same files as the standard `generate route` command, but the service will return the provided JSON data.


## Project Structure

The generated project follows a structured and scalable architecture:

```
<your_project_name>/
├── api/
│   ├── apis/             # For third-party API integrations
│   ├── decorators/       # Custom decorators (e.g., for authentication)
│   ├── helper/           # Helper functions and utilities
│   ├── models/           # SQLAlchemy database models
│   ├── repositories/     # Data access layer
│   ├── routes/           # API endpoints (controllers)
│   ├── schemas/          # Data validation schemas
│   ├── services/         # Business logic layer
│   └── startup/          # Application startup and configuration
├── .github/
│   └── workflows/        # CI/CD workflows
├── .gitignore
├── docker-compose.yml
├── Dockerfile
└── requirements.txt
```

## Telemetry

BackAnt CLI includes **opt-in** anonymous telemetry to help us improve the tool. On first run, you'll be asked if you want to participate.

### Quick Disable

```bash
# Environment variable (permanent)
export DO_NOT_TRACK=1

# Per-command flag
ant --no-telemetry generate api my-project

# View telemetry settings
ant --privacy
```

We **never** collect file paths, project names, usernames, or any personally identifiable information. See [docs/telemetry.md](docs/telemetry.md) for full details.

## Contributing

Contributions are welcome! If you have any ideas, suggestions, or bug reports, please open an issue or submit a pull request.

### Development Setup

1.  **Clone the repository:**
    ```bash
    git clone https://github.com/backant/backant-cli.git
    ```
2.  **Create a virtual environment:**
    ```bash
    python3 -m venv venv
    source venv/bin/activate
    ```
3.  **Install the dependencies:**
    ```bash
    pip install -r requirements.txt
    ```
4.  **Install the CLI in editable mode:**
    ```bash
    pip install -e .
    ```

Now you can run the CLI locally using the `ant` command.
