aegra-cli

Aegra CLI - Command-line interface for managing self-hosted agent deployments.

Aegra is an open-source, self-hosted alternative to LangSmith Deployments. Use this CLI to initialize projects, run development servers, and manage Docker services.

Installation

From PyPI

pip install aegra-cli

From Source

# Clone the repository
git clone https://github.com/aegra/aegra.git
cd aegra

# Install all workspace packages
uv sync --all-packages

Quick Start

# Initialize a new Aegra project (prompts for location, template, and name)
aegra init

# Follow the printed next steps
cd <your-project>
cp .env.example .env     # Add your OPENAI_API_KEY
uv sync                  # Install dependencies
uv run aegra dev         # Start PostgreSQL + dev server

Commands

`aegra version`

Show version information for aegra-cli and aegra-api.

aegra version

Output displays a table with versions for both packages.

`aegra init`

Initialize a new Aegra project with configuration files and directory structure.

aegra init [PATH] [OPTIONS]

Arguments:

Argument	Default	Description
`PATH`	`.`	Project directory to initialize

Options:

Option	Description
`-t, --template INT`	Template number (1 = "New Aegra Project", 2 = "ReAct Agent")
`-n, --name STR`	Project name
`--force`	Overwrite existing files if they exist

Templates:

#	Name	Description
1	New Aegra Project	Simple chatbot with basic graph structure
2	ReAct Agent	Tool-calling agent with a tools module

Examples:

# Initialize in current directory
aegra init

# Initialize in a specific directory
aegra init my-project

# Initialize with a specific template and name
aegra init my-project --template 2 --name "My ReAct Agent"

# Initialize in current directory, overwriting existing files
aegra init --force

Created Files:

aegra.json - Graph configuration
pyproject.toml - Python project configuration
.env.example - Environment variable template
.gitignore - Git ignore rules
README.md - Project readme
src/<slug>/__init__.py - Package init file
src/<slug>/graph.py - Graph implementation
src/<slug>/state.py - State schema definition
src/<slug>/prompts.py - Prompt templates
src/<slug>/context.py - Context configuration
src/<slug>/utils.py - Utility functions
src/<slug>/tools.py - Tool definitions (ReAct template only)
docker-compose.yml - Docker Compose for PostgreSQL and API services
Dockerfile - Container build

`aegra dev`

Run the development server with hot reload.

aegra dev [OPTIONS]

Options:

Option	Default	Description
`--host HOST`	`127.0.0.1`	Host to bind the server to
`--port PORT`	`2026`	Port to bind the server to
`--app APP`	`aegra_api.main:app`	Application import path
`-c, --config PATH`		Path to aegra.json config file
`-e, --env-file PATH`		Path to .env file
`-f, --file PATH`		Path to docker-compose.yml file
`--no-db-check`		Skip the automatic database check

Examples:

# Start with defaults (localhost:2026)
aegra dev

# Start on all interfaces, port 3000
aegra dev --host 0.0.0.0 --port 3000

# Start with a custom app
aegra dev --app myapp.main:app

# Start with a specific config and env file
aegra dev --config ./aegra.json --env-file ./.env

# Start without automatic database check
aegra dev --no-db-check

The server automatically restarts when code changes are detected.

`aegra serve`

Run the production server (no hot reload).

aegra serve [OPTIONS]

Options:

Option	Default	Description
`--host HOST`	`0.0.0.0`	Host to bind the server to
`--port PORT`	`2026`	Port to bind the server to
`--app APP`	`aegra_api.main:app`	Application import path
`-c, --config PATH`		Path to aegra.json config file

Examples:

# Start with defaults (0.0.0.0:2026)
aegra serve

# Start with a custom config
aegra serve --config ./aegra.json

`aegra up`

Start services with Docker Compose.

aegra up [SERVICES...] [OPTIONS]

Arguments:

Argument	Description
`SERVICES`	Optional list of specific services to start

Options:

Option	Default	Description
`-f, --file FILE`		Path to docker-compose.yml file
`--build / --no-build`	`--build`	Build images before starting containers (on by default)

Examples:

# Start all services (builds by default)
aegra up

# Start only postgres
aegra up postgres

# Start without building
aegra up --no-build

# Start with a custom compose file
aegra up -f ./docker-compose.yml

`aegra down`

Stop services with Docker Compose.

aegra down [OPTIONS]

Options:

Option	Description
`-f, --file FILE`	Path to docker-compose.yml file
`-v, --volumes`	Remove named volumes declared in the compose file

Examples:

# Stop all services
aegra down

# Stop and remove volumes (WARNING: data will be lost)
aegra down -v

# Stop with a custom compose file
aegra down -f ./docker-compose.yml

Environment Variables

The CLI respects the following environment variables (typically set via .env file):

# Database
POSTGRES_USER=aegra
POSTGRES_PASSWORD=aegra_secret
POSTGRES_HOST=localhost
POSTGRES_DB=aegra

# Authentication
AUTH_TYPE=noop  # Options: noop, custom

# Server (for aegra dev)
HOST=0.0.0.0
PORT=2026

# Configuration
AEGRA_CONFIG=aegra.json

Requirements

Python 3.12+
Docker (for aegra up and aegra down commands)
PostgreSQL (or use Docker)

aegra-api: Core API package providing the Agent Protocol server
aegra: Meta-package that installs both aegra-cli and aegra-api

Development Status
- 4 - Beta
Environment
- Console
Intended Audience
- Developers
License
- OSI Approved :: Apache Software License
Programming Language
- Python :: 3.12
Topic
- Software Development :: Build Tools

Release files for aegra-cli 0.10.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aegra-cli 0.10.6
File	Size	Uploaded
aegra_cli-0.10.6.tar.gz	39.6 kB	Sep 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for aegra-cli 0.10.6
File	Interpreter	ABI	Platform	Reset
aegra_cli-0.10.6-py3-none-any.whl 34.6 kB Sep 25, 2026	Python 3	none	any	Details

Total release size: 74.2 kB

Release files / aegra_cli-0.10.6.tar.gz

Download URL	aegra_cli-0.10.6.tar.gz
Size	39.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`fdbba9e717ce21a94182999a365d5a4fb7a1a8320728dcd0f2157b31a98bf080`
BLAKE2b-256 checksum How to use checksums	`8ecb43b5e109ec3ede731eb61dfbd8a584f659a5a7944c7df5e9527aaddd8210`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / aegra_cli-0.10.6-py3-none-any.whl

Download URL	aegra_cli-0.10.6-py3-none-any.whl
Size	34.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e8ce694f548a3e10173d66c8dd3893fd821377f604ba9f4dbe95e61e443ede3b`
BLAKE2b-256 checksum How to use checksums	`005036defa2fb51eafa7437729cd728b214ff63d0f49fd8b059ba71cb828d510`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`