Installation

Requirements

Python 3.11 or higher
uv (recommended) or pip

Quick start

# uv (recommended — fast, deterministic)
uv add oridecon-cli

# pip
pip install oridecon-cli

oridecon --version
oridecon new project my-app --template web-api
cd my-app
oridecon run

That is the whole install. Open http://127.0.0.1:8000/docs for OpenAPI. The walkthrough is Your First App.

The core oridecon package (Application, Provider, Container, Result, modules, YAML config) is pulled in by the CLI and by every extension. oridecon-contracts installs automatically.

Pin the alpha line when you ship:

uv add "oridecon-cli>=0.1,<0.2"

If oridecon is not on PATH after uv add, run it as uv run oridecon.

Templates

oridecon new project always writes one tree. The template only changes which packages and application.yaml sections land — not the shape of src/.

Template	What it adds
`minimal`	Core only
`api`	JSON API (`oridecon-web`)
`web-api` (default)	Web API with OpenAPI
`graphql`	Web + GraphQL
`worker`	Background tasks
`full`	Web + SQL + auth + cache

There is no --structure flag. Feature types live in domains/. App providers live in app-root di/. See Project Structure.

Add packages later

Install only what you need. Every extension depends only on oridecon and oridecon-contracts — never on each other.

oridecon add database               # oridecon-sql + sql: section
oridecon add auth                   # oridecon-auth + auth: section

uv add oridecon-web                 # ASGI, controllers, OpenAPI
uv add "oridecon-sql[postgres]"     # async Postgres driver extra
uv add oridecon-ai oridecon-ai-llm  # orchestration + multi-provider LLM
uv add --dev oridecon-testing       # fakes, test beds, compliance suites

oridecon add patches pyproject.toml (via uv add when available) and writes the provider’s default block into application.yaml. The catalog is 54 packages — do not install them on day one. The annotated list lives on The Ecosystem.

Without the CLI

You can compose an app by hand with uv add oridecon oridecon-web and a create_app() factory. The CLI is still the supported path — it lays down the one project tree that generators and oridecon run expect.

Verify

oridecon --version
python -c "import oridecon; print(oridecon.__version__)"
oridecon run

You should see OpenAPI at /docs. That is the “it works” check.

Next Steps

Your First App — scaffold, run, add a route
For coding agents — read order, repo map, recipes
Agent skills — Claude Code, Cursor, OpenCode pack
Common mistakes — fail vs fix
Project Structure — the tree the CLI writes
The Ecosystem — every package, grouped by purpose