or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

command-execution.md configuration-management.md index.md version-management.md

tile.json

Configuration Management

Environment-aware configuration system supporting custom installation directories and initialization of required folder structures.

Capabilities

Initialization Functions

Core configuration setup and directory management.

/**
 * Initialize GitBook CLI configuration and create required directories
 * Creates ~/.gitbook and ~/.gitbook/versions directories
 * @returns void
 */
function init(): void;

/**
 * Set custom root directory for GitBook CLI storage
 * @param root - Absolute path to new root directory
 * @returns void (updates module exports with new paths)
 */
function setRoot(root): void;

Usage Examples:

const config = require('gitbook-cli/lib/config');

// Initialize with default configuration
config.init(); // Creates ~/.gitbook and ~/.gitbook/versions

// Use custom storage location  
config.setRoot('/opt/gitbook-storage');
config.init(); // Creates /opt/gitbook-storage and /opt/gitbook-storage/versions

console.log('GitBook storage root:', config.ROOT);
console.log('Versions directory:', config.VERSIONS_ROOT);

Configuration Constants

Environment-aware constants for GitBook CLI operation.

/**
 * GitBook version requirement constraint
 * Used to validate installable GitBook versions
 */
const GITBOOK_VERSION: string; // '>1.x.x'

/**
 * Root directory for GitBook CLI storage
 * Resolved from GITBOOK_DIR environment variable or ~/.gitbook
 */
const ROOT: string;

/**
 * Directory where GitBook versions are installed
 * Subdirectory 'versions' under ROOT
 */
const VERSIONS_ROOT: string;

Usage Examples:

const config = require('gitbook-cli/lib/config');

console.log('Supported GitBook versions:', config.GITBOOK_VERSION);
console.log('Storage location:', config.ROOT);
console.log('Versions stored at:', config.VERSIONS_ROOT);

// Check if version meets requirements
const semver = require('semver');
if (semver.satisfies('2.6.7', config.GITBOOK_VERSION)) {
  console.log('Version 2.6.7 is supported');
}

Environment Configuration

GitBook CLI respects several environment variables for configuration:

/**
 * Environment variables affecting configuration:
 * 
 * GITBOOK_DIR - Custom root directory (overrides ~/.gitbook)
 * HOME - User home directory for default storage location
 * DEBUG - Enable debug output for troubleshooting
 */

Environment Variable Examples:

# Use custom storage directory
export GITBOOK_DIR="/opt/gitbook"
gitbook fetch latest

# Enable debug output
export DEBUG=1
gitbook build . --debug

# Check effective configuration
node -e "console.log(require('gitbook-cli/lib/config'))"

Directory Structure

GitBook CLI creates and manages the following directory structure:

ROOT (default: ~/.gitbook)
├── versions/
│   ├── 2.6.7/           # GitBook version installation
│   │   ├── package.json
│   │   ├── lib/
│   │   └── bin/
│   ├── 3.0.0-beta.1/    # Pre-release version
│   ├── latest -> 2.6.7  # Symlink for alias
│   └── dev -> /local/path # Development alias
└── config.json          # Future configuration storage

Error Handling

Configuration operations can encounter several error conditions:

DirectoryCreationError: When storage directories cannot be created
PermissionError: When insufficient permissions for storage location
EnvironmentError: When HOME directory is not available and GITBOOK_DIR not set
PathResolutionError: When custom root path cannot be resolved

try {
  config.init();
} catch (error) {
  if (error.code === 'EACCES') {
    console.error('Permission denied. Try running with sudo or set GITBOOK_DIR to writable location');
  } else if (error.code === 'ENOENT') {
    console.error('Parent directory does not exist:', error.path);
  } else {
    console.error('Initialization failed:', error.message);
  }
}

Integration with Other Modules

Configuration management integrates with other GitBook CLI modules:

Version Storage

const local = require('gitbook-cli/lib/local');
const config = require('gitbook-cli/lib/config');

// Local version management uses configuration paths
const versions = local.versions(); // Scans config.VERSIONS_ROOT

Registry Installation

const registry = require('gitbook-cli/lib/registry');
const config = require('gitbook-cli/lib/config');

// Registry installs to configured versions directory
const version = await registry.install('2.6.7'); // Installs to config.VERSIONS_ROOT

CLI Integration

// CLI binary initializes configuration on startup
const manager = require('gitbook-cli');
manager.init(); // Calls config.init() internally

Version

Tile

Files