Skip to content

getting-started.md

Latest commit

 

History

History
139 lines (92 loc) · 4.86 KB

getting-started.md

File metadata and controls

139 lines (92 loc) · 4.86 KB
Raw

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:

$ 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.

!!! tip "Prefer an isolated tool install?" Use uv to install it as a standalone tool, off your project's dependencies:

```console
$ 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:

$ 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.

!!! info "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.

!!! warning "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:

$ 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.

!!! example "Check it" Want to pick the model up front? Pass it on the command line:

```console
$ 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:

> 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:

> /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:

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

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

> !git status
> !make test

!!! tip "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.