> ## Documentation Index
> Fetch the complete documentation index at: https://docs.potpie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Commands

> Task-oriented context retrieval and durable learning commands: resolve, search, and record.

These commands are the smallest stable user-facing surface for interacting with Potpie's context engine.

## Command Family

| Command | Purpose |
| - | - |
| `potpie resolve` | Pull a bounded context package for a task. |
| `potpie search` | Run a narrow follow-up lookup against known entities or phrases. |
| `potpie record` | Persist a durable project learning back into the graph. |

Internally, these are treated as the core context contract. New use cases tend to become new option values rather than brand-new top-level commands.

## `potpie resolve`

```bash theme={null}
potpie resolve [OPTIONS] TASK
```

Pulls the context an agent or developer should read before starting work.

### Arguments

| Argument | Type | Description |
| - | - | - |
| `task` | `str` | The task to pull context for. Required. |

### Options

| Option | Type | Description |
| - | - | - |
| `--intent` | `str` | Work intent. Defaults to `feature`. |
| `--include` | `str` | Comma-separated include families to constrain the returned context. |
| `--mode` | `str` | Retrieval mode: `fast`, `balanced`, `verify`, or `deep`. |
| `--pot` | `str` | Pot to resolve against. |

### Examples

```bash theme={null}
potpie resolve "what should I know before working in this repository?"
potpie resolve "trace the authentication flow" --intent debug --mode deep
potpie resolve "prepare for a refactor of billing webhooks" --include code,history,decisions
```

## `potpie search`

```bash theme={null}
potpie search [OPTIONS] QUERY
```

Use this when you already know the rough phrase, entity, workflow, bug, or convention you need to narrow down.

### Arguments

| Argument | Type | Description |
| - | - | - |
| `query` | `str` | Phrase or entity to look up. Required. |

### Options

| Option | Type | Description |
| - | - | - |
| `--include` | `str` | Include-family filter. |
| `--pot` | `str` | Pot to search. |

### Examples

```bash theme={null}
potpie search "authentication flow"
potpie search "deploy rollback runbook"
potpie search "rate limiter middleware" --include code,docs
```

## `potpie record`

```bash theme={null}
potpie record [OPTIONS]
```

Writes a durable project learning back into the context system.

### Options

| Option | Type | Description |
| - | - | - |
| `--type` | `str` | Record type such as `fix`, `decision`, or `preference`. Required. |
| `--summary` | `str` | The durable learning to persist. Required. |
| `--scope` | `str` | Scope in `key:value` form, for example `service:inventory-svc`. |
| `--pot` | `str` | Pot to write into. |

### Examples

```bash theme={null}
potpie record --type decision --summary "Prefer the context-engine CLI for graph work"
potpie record --type fix --summary "Invoice retries depend on Stripe webhook idempotency" --scope service:billing
potpie record --type preference --summary "Use feature flags for staged rollouts" --scope team:platform
```

## When To Use Which

| Need | Command |
| - | - |
| "I am about to work on X. Give me the bounded context." | `resolve` |
| "I know the name or phrase. Narrow it down." | `search` |
| "This is important enough to keep in the project memory." | `record` |

## Typical Flow

```bash theme={null}
potpie resolve "debug intermittent webhook failures" --intent debug --mode verify
potpie search "stripe retry handler"
potpie record --type fix --summary "Webhook retries fan into the async retry worker" --scope service:payments
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.