What is search?

The search command performs a cross-type search across functions, classes, variables, and files in your indexed codebase. It supports text search, semantic (vector) search, hybrid search, result grouping, and advanced filtering.

ciak search [OPTIONS] <QUERY>

Where you see it in the product

• CLI — ciak search "authentication handler" for quick searches from the terminal.
• MCP — the search_code MCP tool uses the same underlying search engine.

Behavior and options

Default ranking behavior

For text-based unified search, CIAK applies path-aware ranking priors by default:

• implementation paths (for example src/**, lib/**) get a modest boost
• test/spec/sample paths (for example **/tests/**, **/*.spec.*) are demoted

This helps keep core implementation symbols above test helpers for broad queries while still allowing strong exact matches in tests to surface.

You can tune or disable this behavior in [ranking] config.

For MCP callers using search_code, set include_ranking_factors: true to receive per-result explainability fields (base_score, path_boost_demotion, anchor_bonus, test_penalty, final_score).

search_code also returns top-level ranking diagnostics metadata (ranking_profile, scoring_version, factors_enabled) so clients can trace which scorer profile/version produced a response. This metadata is independent of include_ranking_factors.

For MCP callers using search_code, snippet shaping is also configurable:

• context_granularity: "method" prefers method/function-level snippets for action or flow tracing
• context_granularity: "class" keeps class-level snippets when broader structure is more useful
• context_granularity: "auto" switches to method-level snippets for action/flow-style queries and otherwise keeps normal behavior

MCP callers can also set max_snippet_lines_per_result to cap snippet size. When a snippet is capped, CIAK appends a marker such as ... [truncated N lines] and returns truncation metadata alongside the snippet. The current default cap is 50 lines per result.

Basic options

Option	Description
<QUERY>	Search query (required, positional)
-p, --project <PROJECT>	Project to search in
-L, --language <LANG>	Filter results by language
-l, --limit <N>	Maximum results to return (defaults: text 20, semantic/hybrid 10)

Search modes

Option	Description
--semantic	Enable semantic vector search (requires embeddings)
--hybrid	Combine text and vector search for best results
--min-score <0.0-1.0>	Minimum semantic similarity score to keep (default: 0.3)
--compact	Compact semantic output: path + score + short snippet
--embedding-model <MODEL>	Specify embedding model for semantic search
--case-sensitive	Case-sensitive text search
--whole-word	Match whole words only
--include-files	Include file-level results

Result presentation

Option	Description
--with-context	Include surrounding code lines in results
--context-lines <N>	Number of context lines before and after (default: 5, max: 10)
--group-by <STRATEGY>	Group results by symbol_type or file_type
--min-group-size <N>	Minimum results per group to display (default: 1)

Advanced filters

Option	Description
--path-patterns <PATTERNS>	Comma-separated glob patterns (e.g., src/**/*.rs,!tests/**)
--parent-class <CLASS>	Filter by parent class name
--implements <INTERFACE>	Filter by implemented interface
--visibility <LEVELS>	Comma-separated visibility levels: public, private, protected, internal, package

Examples

Example 1 — Basic text search

ciak search "authentication"

Example 2 — Semantic search with context

ciak search "function that validates JWT tokens" --semantic --with-context --min-score 0.35

Example 3 — Filtered search for public TypeScript classes

ciak search "service" --language typescript --visibility public --group-by symbol_type

Example 4 — Hybrid search with path filtering

ciak search "database connection" --hybrid --path-patterns "src/**/*.ts,!node_modules/**" --compact

Input and output example

Representative CLI output (truncated; exact formatting may vary by version):

Input

ciak search "authentication handler" --hybrid --with-context --limit 3

Output

Found 3 results for: authentication handler

[1] src/auth/service.ts:42  function  score: 0.94
    async function authenticateUser(token: string) { ... }
    Context:
      40 | export async function login(...) {
      41 |   ...
      42 |   async function authenticateUser(token: string) {
      43 |     ...

[2] src/auth/controller.ts:18  method  score: 0.88
    handleAuthCallback(req, res) { ... }

Related concepts

• scan — must be run first to populate the database.
• query — type-specific search (function, class, variable, file).
• MCP Tools — search_code — the MCP equivalent of this command.