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

# Unix Piping

> Scripting and automation patterns

Codanna is a local code intelligence MCP server and CLI for AI coding agents. All commands support `--json` for structured output using a unified envelope schema, so you can chain queries through `jq`, `xargs`, and Unix pipes.

## JSON Envelope Schema

All `--json` output follows a consistent envelope structure (schema version 1.0.0):

```json theme={null}
{
  "type": "result",
  "status": "success",
  "code": "OK",
  "exit_code": 0,
  "message": "Found 1 symbol(s)",
  "hint": "Symbol found with full context. Explore 'get_calls' to see what it calls, 'find_callers' to see usage, or 'analyze_impact' to understand change implications.",
  "data": [...],
  "meta": {
    "schema_version": "1.0.0",
    "entity_type": "symbol",
    "count": 1,
    "query": "Envelope"
  }
}
```

### Envelope Fields

| Field | Type | Description |
| :- | :- | :- |
| `type` | `"result"` \| `"error"` | Message type for stream discrimination; streaming commands add `"begin"` and `"summary"` |
| `status` | `"success"` \| `"not_found"` \| `"partial_success"` \| `"error"` | Operation outcome |
| `code` | string | Machine-readable code: `OK`, `NOT_FOUND`, `PARSE_ERROR`, `INDEX_ERROR`, `INVALID_QUERY`, `INTERNAL_ERROR` |
| `exit_code` | integer | Unix exit code (0-255) |
| `message` | string | Human-readable description |
| `hint` | string? | AI assistant guidance for next steps |
| `data` | any? | Payload on success (null on error) |
| `error` | object? | Error details with `suggestions[]` and `context` |
| `meta` | object | Metadata: `schema_version`, `entity_type`, `count`, `query`, `lang`, `duration_ms`, `truncated`, `depth` |

### Exit Codes

| Code | Status | Meaning |
| :- | :- | :- |
| `0` | `success` | Operation completed with results |
| `1` | `not_found` | No results found |
| `2` | `error` | Operation failed |

<Note>
  One exit code carries no envelope: a stale index (built by a binary with different output semantics) refuses with exit `7` and the heal command on stderr — stdout stays empty, so `jq` receives no input. Gate scripts on the exit code, not only on parsed output.
</Note>

### Streaming Mode

`codanna dump` (v0.14.0+) uses the envelope's streaming mode: a `begin` envelope, one `result` envelope per line for every symbol and relationship, and a terminal `summary` envelope with totals. The per-line shape makes the whole graph pipeable:

```bash theme={null}
codanna dump --edges --relation calls | jq -r 'select(.type=="result") | .data | "\(.from.name) -> \(.to.name)"'
```

See the [CLI reference](/reference/cli#dump) for flags and row shapes.

## Field Filtering

Use `--fields` to project `data` items down to the keys you need. Entries are top-level keys or dotted paths into nested values (`symbol.name`); output preserves nesting. Top-level shapes differ per tool: `find_symbol` items carry `symbol`, `file_path`, and `relationships`; `search_symbols` items carry `symbol`, `score`, and `highlights`. A field whose first segment does not exist at the item's top level is rejected with an `INVALID_QUERY` error envelope listing the available fields (exit `2`). A deeper segment missing on an individual item omits that leaf for that item only.

```bash theme={null}
codanna mcp find_symbol name:Envelope --json --fields symbol.name,file_path
```

Output:

```json theme={null}
{
  "code": "OK",
  "data": [
    {
      "file_path": "src/io/envelope.rs",
      "symbol": {
        "name": "Envelope"
      }
    }
  ],
  "exit_code": 0,
  "hint": "Symbol found with full context. Explore 'get_calls' to see what it calls, 'find_callers' to see usage, or 'analyze_impact' to understand change implications.",
  "message": "Found 1 symbol(s)",
  "meta": {
    "count": 1,
    "entity_type": "symbol",
    "query": "Envelope",
    "schema_version": "1.0.0"
  },
  "status": "success",
  "type": "result"
}
```

The envelope structure (type, status, code, meta) is always included. Only `data` items are filtered; projected output serializes keys alphabetically.

Available with: `codanna mcp <tool> --json --fields` and `codanna retrieve <subcommand> --json --fields`

## Error Response

Errors include suggestions and context for recovery:

```bash theme={null}
codanna retrieve callers parse --json
```

```json theme={null}
{
  "type": "error",
  "status": "error",
  "code": "INVALID_QUERY",
  "exit_code": 2,
  "message": "Ambiguous: found 32 symbol(s) named 'parse'",
  "hint": "Use: codanna retrieve callers symbol_id:<id>",
  "data": null,
  "error": {
    "suggestions": [
      "symbol_id:1581",
      "symbol_id:3975"
    ],
    "context": [
      {
        "file_path": "src/parsing/swift/parser.rs",
        "kind": "Method",
        "line": 1653,
        "symbol_id": 1581
      }
    ]
  },
  "meta": {
    "schema_version": "1.0.0",
    "entity_type": "callers",
    "query": "parse"
  }
}
```

## Not Found Response

```bash theme={null}
codanna mcp find_symbol name:NonExistent --json
```

```json theme={null}
{
  "type": "result",
  "status": "not_found",
  "code": "NOT_FOUND",
  "exit_code": 1,
  "message": "Symbol 'NonExistent' not found",
  "hint": "Symbol not found. Use 'search_symbols' with fuzzy matching or 'semantic_search_docs' for broader search.",
  "data": null,
  "meta": {
    "schema_version": "1.0.0",
    "entity_type": "symbol",
    "query": "NonExistent"
  }
}
```

## Piping Examples

### Extract Data with jq

```bash theme={null}
# Get symbol names from search results
codanna mcp semantic_search_with_context query:"authentication" limit:2 --json | \
  jq -r '.data[].symbol.name'

# Get file paths only (null-safe: .data is null on not_found)
codanna mcp find_symbol name:Envelope --json | \
  jq -r '.data[]? | .file_path'

# Check status before processing
codanna mcp find_symbol name:Envelope --json | \
  jq -e '.status == "success"' && echo "Found"
```

### Chain Commands

```bash theme={null}
# Find symbol, then trace its callers
codanna mcp semantic_search_with_context query:"config parser" limit:1 --json | \
  jq -r '.data[0].symbol.id' | \
  xargs -I {} codanna mcp find_callers symbol_id:{} --json | \
  jq -r '.data[] | "\(.name) - \(.file_path)"'
```

### Debug with Error Messages

```bash theme={null}
# Pipe error output from any tool to find relevant code
./my_app 2>&1 | grep -i "error\|exception" | head -1 | \
  xargs -I {} codanna mcp semantic_search_with_context query:"{}" limit:3

# From test runner
cargo test 2>&1 | grep "panicked" | \
  xargs -I {} codanna mcp semantic_search_with_context query:"{}" limit:3
```

### Filter Large Results

```bash theme={null}
# Get only names and file paths for many symbols
codanna mcp search_symbols query:parse limit:20 --json --fields symbol.name,symbol.file_path | \
  jq -r '.data[] | "\(.symbol.name): \(.symbol.file_path)"'
```

## Next Steps

<CardGroup cols={2}>
  <Card title="CLI Reference" icon="terminal" href="/reference/cli">
    Complete command reference.
  </Card>

  <Card title="Debugging" icon="bug" href="/reference/debugging">
    Troubleshooting and logs.
  </Card>
</CardGroup>


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