Cortex Configuration File Reference

This page provides detailed information about the Cortex configuration file, its format, and available options.

Overview

The Cortex configuration file allows you to customize the behavior of the Cortex CLI and set default options for various commands. The configuration uses YAML format and is located at ~/.config/cortex.yml by default.

File Location

The default location for the Cortex configuration file is:

• ~/.config/cortex.yml (Unix/Linux/macOS)
• %USERPROFILE%\.config\cortex.yml (Windows)

You can override this location by using the --config flag when running Cortex commands:

cortex --config /path/to/custom-config.yml <command>

Configuration Format

The configuration file uses YAML format and is organized into sections that correspond to different aspects of the Cortex CLI:

# Example structure
auth:
  # Authentication settings
  
api:
  # API-related settings
  
defaults:
  # Default values for commands
  
plugins:
  # Plugin configurations

Configuration Sections

auth

The auth section contains authentication-related settings.

Option	Type	Default	Description
token_path	string	~/.config/cortex/tokens.json	Path where authentication tokens are stored
refresh_threshold	integer	86400	Time in seconds before token refresh
scope	string	full	Authentication scope (full, read, write)

Example:

auth:
  token_path: ~/.cortex/tokens.json
  refresh_threshold: 43200
  scope: full

api

The api section configures API connection settings.

Option	Type	Default	Description
endpoint	string	https://api.cortexcli.com/v1	API endpoint URL
timeout	integer	30	Request timeout in seconds
retry_attempts	integer	3	Number of retry attempts for failed requests
retry_delay	integer	5	Delay between retries in seconds

Example:

api:
  endpoint: https://custom-endpoint.example.com/v1
  timeout: 60
  retry_attempts: 5
  retry_delay: 2

defaults

The defaults section sets default values for various commands.

Option	Type	Default	Description
output	string	text	Default output format (text, json, yaml)
color	boolean	true	Whether to use colored output
verbose	boolean	false	Enable verbose output by default

Example:

defaults:
  output: json
  color: true
  verbose: true

test

The test section configures test-related settings.

Option	Type	Default	Description
parallel	boolean	false	Run tests in parallel by default
reporter	string	standard	Default test reporter
timeout	integer	30	Test timeout in seconds
path	string	./tests	Default test directory

Example:

test:
  parallel: true
  reporter: detailed
  timeout: 60
  path: ./custom-tests

lint

The lint section configures linting settings.

Option	Type	Default	Description
rules	string	standard	Default ruleset to use
fix	boolean	false	Automatically fix issues when possible
ignore_patterns	array	[]	Patterns to ignore

Example:

lint:
  rules: strict
  fix: true
  ignore_patterns:
    - "*.test.js"
    - "node_modules/**"

plugins

The plugins section configures plugin settings.

Option	Type	Default	Description
directory	string	~/.cortex/plugins	Directory for installed plugins
auto_update	boolean	true	Automatically update plugins
disabled	array	[]	List of disabled plugins

Example:

plugins:
  directory: ~/custom-plugins
  auto_update: false
  disabled:
    - legacy-plugin

logging

The logging section configures logging behavior.

Option	Type	Default	Description
level	string	info	Log level (debug, info, warn, error)
file	string	~/.cortex/logs/cortex.log	Log file location
max_size	integer	10	Maximum log file size in MB
max_files	integer	5	Number of log files to keep

Example:

logging:
  level: debug
  file: ~/logs/cortex-custom.log
  max_size: 20
  max_files: 10

cache

The cache section configures caching behavior.

Option	Type	Default	Description
directory	string	~/.cache/cortex	Cache directory location
ttl	integer	3600	Default cache TTL in seconds
max_size	integer	100	Maximum cache size in MB

Example:

cache:
  directory: ~/custom-cache
  ttl: 7200
  max_size: 200

Complete Example

Here's a complete example of a Cortex configuration file with commonly used settings:

# Cortex CLI Configuration (~/.config/cortex.yml)

auth:
  token_path: ~/.cortex/tokens.json
  refresh_threshold: 43200
  scope: full

api:
  endpoint: https://api.cortexcli.com/v1
  timeout: 45
  retry_attempts: 3
  retry_delay: 5

defaults:
  output: text
  color: true
  verbose: false

test:
  parallel: true
  reporter: detailed
  timeout: 60
  path: ./tests

lint:
  rules: standard
  fix: false
  ignore_patterns:
    - "*.test.js"
    - "node_modules/**"

plugins:
  directory: ~/.cortex/plugins
  auto_update: true
  disabled: []

logging:
  level: info
  file: ~/.cortex/logs/cortex.log
  max_size: 10
  max_files: 5

cache:
  directory: ~/.cache/cortex
  ttl: 3600
  max_size: 100

Managing Configuration

You can manage your configuration using the cortex config command:

Subcommand	Description	Example
get	Get a configuration value	cortex config get api.timeout
set	Set a configuration value	cortex config set api.timeout=60
list	List all configurations	cortex config list
reset	Reset to default values	cortex config reset

For more information about Cortex CLI commands, refer to the API Reference page.