Fractary Codex CLI

Command-line interface for Fractary Codex knowledge management system.

Installation

Global Installation

npm install -g @fractary/codex-cli

Local Development

# From repository root
npm install
cd cli
npm run build
npm link

Usage

fractary-codex [command] [options]

Commands

init - Initialize Configuration

Initialize Codex v3.0 with YAML configuration in your project.

fractary-codex init [options]

Options:
  --force    Overwrite existing configuration

Example:

fractary-codex init
# Creates .fractary/codex.yaml and .codex-cache/

fetch - Fetch Documents

Fetch documents by codex:// URI reference with intelligent caching.

fractary-codex fetch <uri> [options]

Arguments:
  uri                  Codex URI (e.g., codex://org/project/path/file.md)

Options:
  --bypass-cache       Fetch directly from storage, bypassing cache
  --ttl <seconds>      Override default TTL
  --json               Output as JSON with metadata
  --output <file>      Write content to file instead of stdout

Examples:

# Fetch with caching
fractary-codex fetch codex://myorg/myproject/README.md

# Bypass cache
fractary-codex fetch codex://myorg/myproject/README.md --bypass-cache

# JSON output with metadata
fractary-codex fetch codex://myorg/myproject/README.md --json

# Save to file
fractary-codex fetch codex://myorg/myproject/README.md --output local-README.md

cache - Cache Management

Manage the document cache with subcommands for listing, clearing, and viewing statistics.

cache list - List Cache Information

fractary-codex cache list [options]

Options:
  --json    Output as JSON

cache clear - Clear Cache Entries

fractary-codex cache clear [options]

Options:
  --all                Clear entire cache
  --pattern <glob>     Clear entries matching pattern
  --dry-run            Preview without clearing

Examples:

# Clear all cache entries
fractary-codex cache clear --all

# Clear specific pattern
fractary-codex cache clear --pattern "myorg/myproject/**"

# Preview clearing
fractary-codex cache clear --all --dry-run

cache stats - Cache Statistics

fractary-codex cache stats [options]

Options:
  --json    Output as JSON

sync - Bidirectional Synchronization

Synchronize files with codex repository.

sync project - Sync Single Project

fractary-codex sync project [project-name] [options]

Options:
  --to-codex           Sync from project to codex (one-way)
  --from-codex         Sync from codex to project (one-way)
  --bidirectional      Two-way sync (default)
  --dry-run            Preview changes without syncing
  --env <environment>  Environment branch mapping

sync org - Sync Organization

fractary-codex sync org [options]

Options:
  --to-codex           Sync from projects to codex
  --from-codex         Sync from codex to projects
  --bidirectional      Two-way sync (default)
  --dry-run            Preview changes
  --exclude <pattern>  Exclude repositories matching pattern
  --parallel <n>       Number of parallel sync operations (default: 3)

types - Type Registry Management

Manage custom artifact types for classification and caching.

types list - List All Types

fractary-codex types list [options]

Options:
  --custom-only    Show only custom types
  --builtin-only   Show only built-in types
  --json           Output as JSON

types show - Show Type Details

fractary-codex types show <type-name> [options]

Options:
  --json    Output as JSON

types add - Add Custom Type

fractary-codex types add <type-name> [options]

Options:
  --pattern <glob>        File pattern (required)
  --ttl <duration>        Cache TTL (default: 24h)
  --description <text>    Type description

Example:

fractary-codex types add api-schema --pattern "**/*.openapi.{yaml,json}" --ttl 48h --description "OpenAPI schemas"

types remove - Remove Custom Type

fractary-codex types remove <type-name> [options]

Options:
  --json    Output as JSON

health - Diagnostics

Run comprehensive diagnostics on codex setup.

fractary-codex health [options]

Options:
  --json    Output as JSON for CI/CD integration

Checks:

• Configuration validity
• SDK client initialization
• Cache health and statistics
• Storage provider availability
• Type registry status

migrate - Configuration Migration

Migrate legacy v2.x JSON configuration to v3.0 YAML format.

fractary-codex migrate [options]

Options:
  --dry-run    Preview migration without writing
  --json       Output as JSON

Configuration

Codex uses .fractary/codex.yaml for configuration:

organization: myorg
cacheDir: .codex-cache

storage:
  - type: github
    owner: myorg
    repo: codex-core
    ref: main
    token: ${GITHUB_TOKEN}
    priority: 50

  - type: local
    path: ./codex-local
    priority: 10

types:
  custom:
    api-schema:
      description: OpenAPI API schemas
      patterns:
        - "**/*.openapi.yaml"
        - "**/*.openapi.json"
      defaultTtl: 172800  # 48 hours

permissions:
  default: read
  rules:
    - pattern: "sensitive/**"
      permission: admin
      users: ["admin-user"]

sync:
  bidirectional: true
  conflictResolution: latest
  exclude:
    - "node_modules/**"
    - ".git/**"

mcp:
  enabled: true
  port: 3000

Environment Variables

• GITHUB_TOKEN - GitHub personal access token for private repositories
• CODEX_CACHE_DIR - Override default cache directory
• CODEX_ORG - Override organization slug

Development

Build

npm run build

Test

npm test

Type Check

npm run typecheck

Link for Local Testing

npm link
fractary-codex --help

Architecture

The CLI is built on top of the @fractary/codex SDK and uses:

• Commander.js for command-line parsing
• Chalk for colored output
• js-yaml for YAML configuration
• Dynamic imports for fast cold-start performance

All commands use lazy-loading to avoid SDK initialization overhead for simple operations like --help.

License

MIT

Documentation

• Command Reference - Complete command reference for all interfaces
• API Reference - Complete API documentation
• CLI Integration Guide - How to integrate into CLI applications
• Configuration Guide - Configuration reference
• Naming Conventions - Naming standards across all interfaces
• MCP Migration Guide - Migrating to new MCP tool names
• Troubleshooting - Common issues and solutions

Links

• GitHub Repository
• Documentation
• SDK Package
• Issue Tracker