Skip to content

Install & first run

Let's get the pydantic-deep CLI running in your terminal and have your first conversation with it. Install, point it at a model, launch, and start typing — that's the whole path.

Install it

The CLI ships as an extra on the pydantic-deep package:

Bash Session
$ pip install "pydantic-deep[cli]"

That gives you the pydantic-deep command — a Claude Code-style AI coding assistant built on the full pydantic-deep framework.

Prefer an isolated tool install?

Use uv to install it as a standalone tool, off your project's dependencies:

Bash Session
$ uv tool install "pydantic-deep[cli]"

Set an API key

The CLI talks to a model provider, so it needs a key. Set one environment variable for the provider you want:

Bash Session
$ export ANTHROPIC_API_KEY="sk-ant-..."     # Anthropic (Claude)
$ export OPENAI_API_KEY="sk-..."            # OpenAI (GPT)
$ export OPENROUTER_API_KEY="sk-or-..."     # OpenRouter (many models)
$ export GOOGLE_API_KEY="..."               # Google (Gemini)

You only need the one that matches your model. Running Ollama locally needs no key at all.

Where keys are loaded from

You don't have to keep exporting the key every session. The CLI reads keys from several places, and the first one to set a variable wins:

  1. Real shell environment — anything already in os.environ (e.g. export ANTHROPIC_API_KEY=…). Always wins.
  2. ./.pydantic-deep/.env — project-local, ignored by git.
  3. ./.env — your project's .env, if you keep one.
  4. ~/.pydantic-deep/.env — a global fallback for keys you reuse everywhere.

Project files beat the global fallback, so a per-project key in ./.env always shadows a stale global one.

The /provider flow writes them for you

On first launch the CLI walks you through provider setup and saves your key to .pydantic-deep/keys.toml (also git-ignored). You can re-run it any time with the /provider command — no manual file editing required.

Keep keys out of git

Both .pydantic-deep/.env and .pydantic-deep/keys.toml hold secrets. The init command git-ignores .pydantic-deep/ for you; if you add a key to a plain ./.env, make sure it's ignored too.

Launch it

From any project directory, just run:

Bash Session
$ pydantic-deep

That's it — no subcommand needed. The CLI initializes a .pydantic-deep/ folder for the project (config, sessions, logs) and opens the interactive TUI: a rich terminal interface with streaming chat, tool-call visualization, and slash commands.

Check it

Want to pick the model up front? Pass it on the command line:

Bash Session
$ pydantic-deep --model anthropic:claude-sonnet-4-6

--model takes any model string Pydantic AI understands — anthropic:…, openai:…, google-gla:…, openrouter:…, and more. Command-line flags always override your saved config.

Your first conversation

Once the TUI is up, you're in a prompt. Three special first characters change what your input means.

Just type a message and press Enter to talk to the agent:

Text Only
> Read main.py and tell me what it does

The agent reads the file, may run a few tools (you'll see each call appear inline), then streams its answer back.

Type / to open the command picker. Slash commands control the session rather than the agent:

Text Only
> /help          show every command and shortcut
> /model         switch models with an interactive picker
> /context       see how much of the context window you've used
> /clear         start a fresh conversation

Type @ to reference a file. The CLI pops up a file picker and inlines the file's contents into your prompt:

Text Only
> Explain the error handling in @apps/cli/config.py

Type ! to run a shell command directly, without involving the model:

Text Only
> !git status
> !make test

Sensitive tools ask first

When the agent wants to run something like execute, an approval modal pops up: Y to allow once, A to auto-approve, N to deny, Esc to cancel. You stay in control of what actually runs.

Recap

You've got the CLI installed and talking:

  • pip install "pydantic-deep[cli]" (or uv tool install) gives you the pydantic-deep command.
  • Set a provider key as an env var, or let /provider save it — keys load from the shell first, then project .env files, then a global ~/.pydantic-deep/.env.
  • Run pydantic-deep with no arguments to launch the TUI; --model overrides the default.
  • In the prompt, plain text talks to the agent, / opens commands, @ inlines files, and ! runs the shell.

Now let's dig into everything the slash commands can do.