# retrieve — Get a Prepared Prompt by ID

**Script name:** `retrieve`

**Script location:** [`scripts/retrieve.ts`](../../../scripts/retrieve.ts)

**Invoke:**
```bash
npx --yes tsx .opencode/skills/templating-vault/scripts/retrieve.ts \
  --id ID [--config PATH] [--store-dir SPEC...]
```

**CRITICAL:** Always invoke the script using bash and the format noted above.

## Synopsis

```
retrieve.ts --id ID [--config PATH] [--store-dir SPEC...]
```

Retrieves a prepared prompt stored by `render.ts --prepare`. Returns the full
rendered prompt text, the variable schema (literal/non-literal classification from
the template's `schema.yaml`), and the source template reference.

Used by the child agent in the prompt-by-reference protocol. The child calls this
to understand its instructions, then uses `extract.ts` for literal variables and
`set.ts` for non-literal variables.

## Arguments

### Required

| Flag | Type | Description |
|------|------|-------------|
| `--id ID` | string | The prepared prompt ID (returned by `render.ts --prepare`) |

## Output (stdout)

```json
{
  "found": true,
  "id": "imp-001",
  "template_key": "templates.imp_supervisor",
  "content": "Repository base url: https://git.cleverthis.com\nforgejo pat: 92224acf...\n...",
  "variables": {
    "forgejo_pat": {"literal": true, "type": "hex", "description": "Primary bot PAT"},
    "max_workers": {"literal": false, "type": "positive_integer", "description": "Pool size"}
  }
}
```

Not found:
```json
{"found": false, "error": "Prepared prompt \"bad-id\" not found in vault", "id": "bad-id"}
```

## How the Child Agent Uses This

1. Call `retrieve.ts --id <id>` to get the prompt and variable schema
2. Read the `content` to understand the instructions
3. For each variable in `variables` where `literal: true`:
   - Call `extract.ts --source-key prepared.<id> --key <target> --regex '<pattern>'`
4. For each variable where `literal: false`:
   - Call `set.ts --key <target> --value <inferred_value>`
5. Use `get.ts` to read stored values during execution

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success (check `found` field) |
| 1 | Fatal error |

## Dependencies

- Node.js >= 18, `npx tsx`, `js-yaml`
