Unix Piping

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

{
  "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

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.

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:

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

See the CLI reference 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.

codanna mcp find_symbol name:Envelope --json --fields symbol.name,file_path

Output:

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

codanna retrieve callers parse --json

{
  "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

codanna mcp find_symbol name:NonExistent --json

{
  "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

# 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

# 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

# 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

# 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)"'

Overview

Features

Workflows

JSON Envelope Schema

Envelope Fields

Exit Codes

Streaming Mode

Field Filtering

Error Response

Not Found Response

Piping Examples

Extract Data with jq

Chain Commands

Debug with Error Messages

Filter Large Results

Next Steps

CLI Reference

Debugging

​JSON Envelope Schema

​Envelope Fields

​Exit Codes

​Streaming Mode

​Field Filtering

​Error Response

​Not Found Response

​Piping Examples

​Extract Data with jq

​Chain Commands

​Debug with Error Messages

​Filter Large Results

​Next Steps

CLI Reference

Debugging

JSON Envelope Schema

Envelope Fields

Exit Codes

Streaming Mode

Field Filtering

Error Response

Not Found Response

Piping Examples

Extract Data with jq

Chain Commands

Debug with Error Messages

Filter Large Results

Next Steps