Configuration

sqry uses a configuration file for project-level settings and environment variables for runtime performance tuning. Both are optional — sensible defaults apply out of the box.

Config File

sqry stores project configuration at .sqry/graph/config/config.json, relative to your project root. The file is created automatically the first time you run sqry index ..

To view the effective configuration at any time:

cat .sqry/graph/config/config.json
# Or:
sqry config show

The full JSON schema with all available keys:

{
  "indexing": {
    // Maximum file size to index. Files larger than this are skipped.
    // Default: 10485760 (10 MB)
    "max_file_size": 10485760,

    // Maximum directory traversal depth.
    // Default: 100
    "max_depth": 100,

    // Extract scope information (parent/child symbol relationships).
    // Default: true
    "enable_scope_extraction": true,

    // Extract relation information (callers, callees, imports, exports).
    // Default: true
    "enable_relation_extraction": true,

    // Additional directories to exclude during repository detection.
    // Extends the built-in ignored list.
    // Default: []
    "additional_ignored_dirs": []
  },

  "ignore": {
    // Glob patterns (gitignore syntax) for files and directories to exclude.
    // These defaults are applied automatically; add your own patterns as needed.
    "patterns": [
      "node_modules/**",
      "target/**",
      "dist/**",
      "*.min.js",
      "vendor/**",
      ".git/**",
      "__pycache__/**",
      ".venv/**",
      "venv/**",
      ".gradle/**",
      ".idea/**",
      ".vscode/**"
    ]
  },

  "include": {
    // Glob patterns that override ignore patterns.
    // Useful for including specific subdirectories inside ignored paths.
    // Example: ["vendor/internal/**"]
    // Default: []
    "patterns": []
  },

  "languages": {
    // Map custom file extensions to language IDs.
    // Example: { "jsx": "javascript", "tsx": "typescript" }
    "extensions": {},

    // Map specific filenames to language IDs.
    // Example: { "Jenkinsfile": "groovy" }
    "files": {}
  },

  "cache": {
    // Cache directory relative to project root.
    // Default: ".sqry-cache"
    "directory": ".sqry-cache",

    // Enable persistent on-disk cache for 113x faster repeated queries.
    // Default: true
    "persistent": true
  }
}

After editing the config, rebuild the index to apply the changes:

sqry index --force .

Migrating from legacy config: If you have a .sqry-config.toml from an older version, sqry migrates it automatically the next time you run any command. The legacy file can be removed once you have verified the new config is correct.

Environment Variables

Environment variables override config file settings and are useful for CI/CD pipelines, containers, and per-session tuning. They do not persist between sessions.

Cache variables

Variable	Default	Description
`SQRY_CACHE_ROOT`	`.sqry-cache`	Cache directory location. Set to an absolute path to use a shared or SSD-backed location.
`SQRY_CACHE_MAX_BYTES`	`52428800` (50 MB)	Maximum cache size in bytes. When exceeded, older entries are evicted.
`SQRY_CACHE_DISABLE_PERSIST`	`0`	Set to `1` to disable disk persistence (memory-only). Useful in containers or ephemeral CI runners.
`SQRY_CACHE_POLICY`	`lru`	Eviction policy: `lru` (least-recently-used), `tiny_lfu` (admission-filtered hot set), or `hybrid` (LRU window + TinyLFU body).
`SQRY_CACHE_DEBUG`	(unset)	Set to `1` to emit `CacheStats{...}` lines to stderr after every query. Useful for benchmarking and CI validation.

Lexer pool variables

The query lexer uses thread-local buffer pooling to reduce memory allocations. The defaults are appropriate for most workloads.

Variable	Default	Description
`SQRY_LEXER_POOL_MAX`	`4`	Maximum pool size per thread. Set to `0` to disable pooling entirely (useful for micro-benchmarking). Increase for high-concurrency server workloads.
`SQRY_LEXER_POOL_MAX_CAP`	`256`	Buffer capacity limit in tokens. Buffers larger than this are not returned to the pool.
`SQRY_LEXER_POOL_SHRINK_RATIO`	`8`	When a buffer exceeds the capacity limit, it is shrunk by this ratio before being discarded.

JSON Plugin

The JSON language plugin (sqry-lang-json) has safety limits for traversal depth and node count.

Variable	Default	Range	Description
`SQRY_JSON_MAX_DEPTH`	`64`	8–256	Maximum nesting depth for JSON traversal
`SQRY_JSON_MAX_NODES`	`500000`	1,000–5,000,000	Maximum nodes extracted per JSON file

Gitignore

The .sqry-cache/ directory holds binary AST cache files that should not be committed. The .sqry/ directory contains the graph index snapshot and config; whether to commit it depends on your workflow.

Recommended .gitignore additions:

# Always ignore the cache (large binary files)
.sqry-cache/

# Ignore the full sqry state directory (recommended for most projects)
.sqry/

If you want to commit the configuration file but not the index itself, you can be more selective:

.sqry-cache/
.sqry/graph/snapshot.sqry

The .sqryignore file (same gitignore syntax, placed at the project root) provides a sqry-specific ignore list that does not affect git. This is useful for excluding generated files or test fixtures from indexing without modifying .gitignore.

Config Commands

sqry provides subcommands for managing configuration without editing JSON by hand:

# Initialize config with defaults
sqry config init

# Show the full effective configuration
sqry config show

# Get a single setting
sqry config get indexing.max_file_size

# Set a value
sqry config set indexing.max_file_size 20971520

# Validate config file integrity
sqry config validate

Query Aliases

Save frequently used queries as named aliases to avoid retyping complex predicates:

# Create an alias
sqry config alias set dead-code "unused:true AND kind:function AND visibility:public"
sqry config alias set auth-callers "callers:authenticate AND lang:rust"

# List all aliases
sqry config alias list

# Run an alias by name
sqry query @dead-code
sqry query @auth-callers

Aliases can also be managed with the dedicated alias command:

# List aliases (local and global)
sqry alias list
sqry alias list --global

# Show alias details
sqry alias show dead-code

# Rename an alias
sqry alias rename dead-code unused-public

# Delete an alias
sqry alias delete unused-public

Scope: By default, aliases are saved to the project’s .sqry/ directory. Use --global to save to ~/.config/sqry/ for aliases that should be available across all projects.

MCP Server Variables

When running sqry as an MCP server, these variables control server behavior:

Variable	Default	Description
`SQRY_MCP_WORKSPACE_ROOT`	auto	Security boundary — queries are scoped to this path
`SQRY_MCP_MAX_OUTPUT_BYTES`	`50000`	Maximum response payload size
`SQRY_MCP_TIMEOUT_MS`	`30000`	Request timeout
`SQRY_MCP_RETRY_DELAY_MS`	`500`	Retry delay for transient failures
`SQRY_MCP_ENGINE_CACHE_CAPACITY`	`5`	Max cached workspace engines
`SQRY_MCP_DISCOVERY_CACHE_CAPACITY`	`100`	Max cached workspace discovery paths
`SQRY_MCP_TRACE_PATH_CACHE_CAPACITY`	`256`	Trace path result cache size
`SQRY_MCP_SUBGRAPH_CACHE_CAPACITY`	`128`	Subgraph result cache size
`SQRY_MCP_QUERY_CACHE_TTL_SECS`	`300`	Query cache time-to-live (seconds)
`SQRY_MCP_MAX_CROSS_LANG_EDGES`	`50000`	Cross-language edge result limit

See also MCP Response Redaction for the SQRY_REDACT_* variables.

Additional Runtime Variables

Variable	Default	Description
`SQRY_PAGER`	`$PAGER`	Custom pager command (e.g., `less -R`)
`SQRY_NO_HISTORY`	`0`	Set to `1` to disable query history recording
`SQRY_MMAP_THRESHOLD`	`10485760`	Memory-map files larger than this (bytes)
`SQRY_FALLBACK_ENABLED`	`1`	Enable semantic→text search fallback
`SQRY_MIN_SEMANTIC_RESULTS`	`1`	Min semantic results before falling back to text
`SQRY_TEXT_CONTEXT_LINES`	`2`	Context lines for text search results
`SQRY_MAX_TEXT_RESULTS`	`1000`	Max text search results
`SQRY_SHOW_SEARCH_MODE`	`0`	Display which search mode (semantic/text) was used
`SQRY_FUZZY_USE_JACCARD`	`0`	Use Jaccard similarity for fuzzy matching

Edit this page on GitHub →