CTX Docs

Appearance

Variables in configuration ​

CTX supports various types of variables throughout your configuration files, including environment variables, predefined system variables, and custom configuration variables.

Variable Types ​

1. Custom Configuration Variables ​

You can define custom variables directly in your configuration files:

yaml
variables:
  version: 1.0.0
  environment: development
  project_name: Context Generator
  api_token: qwd-qwe123-1231

2. Environment Variables ​

System environment variables loaded from your operating system or .env files.

3. Predefined Variables ​

Built-in system values automatically available in all configurations.

Using Variables in Configuration ​

You can reference variables using either ${VAR_NAME} or syntax in most configuration fields.

Example ​

yaml
variables:
  version: 1.0.0
  environment: development
  project_name: Context Generator

documents:
  - description: "{{project_name}} Documentation"
    outputPath: docs/{{environment}}/{{project_name}}-{{version}}.md
    sources:
      - type: text
        description: Generated on ${DATETIME}
        content: |
          # {{project_name}} v{{version}}
          - Environment: {{environment}}
          - Generated by: ${USER}
          - Hostname: ${HOSTNAME}
          - Operating System: ${OS}

Variable Resolution Priority ​

When a variable is defined in multiple places, it is resolved in the following order of priority:

  1. Custom Configuration Variables (highest priority) - Defined in the variables section
  2. Environment Variables - From system or .env files
  3. Predefined Variables (lowest priority) - Built-in system values

Built-in Predefined Variables ​

Date and Time ​

  • ${DATETIME} - Current date and time (e.g., 2024-03-22 14:33:00)
  • ${DATE} - Current date (e.g., 2024-03-22)
  • ${TIME} - Current time (e.g., 14:33:00)
  • ${TIMESTAMP} - Current Unix timestamp

System Information ​

  • ${USER} - Current system user
  • ${HOME_DIR} - User's home directory
  • ${TEMP_DIR} - System temporary directory
  • ${OS} - Operating system name
  • ${HOSTNAME} - Computer hostname
  • ${PWD} - Current working directory

Loading Variables from .env Files ​

You can use the --env option when running the CLI to load environment variables from a file.

CLI Examples ​

bash
# Load variables from the default .env file
ctx --env

# Load from a custom environment file
ctx --env=.env.local

# Do not load any environment variables (default behavior)
ctx

Use Cases for Custom Variables ​

Custom variables are particularly useful for:

  1. Project Metadata: Version numbers, project names, environments
  2. Dynamic Paths: Generate different output paths based on environment
  3. API Credentials: Store tokens and keys in one place
  4. Template Values: Reuse common text across multiple documents
  5. Import Control: Use variables in import paths to control what gets imported

Examples ​

Complex Document Structure with Variables ​

yaml
variables:
  version: 2.1.0
  company: Acme Corp
  api_base: https://api.example.com/v2
  environment: staging

documents:
  - description: "{{company}} API Documentation"
    outputPath: docs/{{environment}}/api-{{version}}.md
    sources:
      - type: url
        urls:
          - "{{api_base}}/schema"
        headers:
          Authorization: "Bearer {{API_TOKEN}}"
      - type: text
        content: |
          # {{company}} API Documentation
          Version: {{version}}
          Environment: {{environment}}

          Generated on {{DATETIME}} by {{USER}}