or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

cli-commands.md configuration.md index.md programmatic-api.md

tile.json

Configuration

Configuration management through .nirc files and environment variables, allowing users to set default and global package managers.

Capabilities

Configuration Management

Load and manage ni configuration from files and environment variables.

/**
 * Get current ni configuration
 * @returns Promise resolving to configuration object
 */
function getConfig(): Promise<Config>;

/**
 * Get default package manager agent
 * @param programmatic - Running in programmatic mode
 * @returns Promise resolving to default agent or 'prompt'
 */
function getDefaultAgent(programmatic?: boolean): Promise<Agent | 'prompt'>;

/**
 * Get global package manager agent
 * @returns Promise resolving to global agent
 */
function getGlobalAgent(): Promise<Agent>;

interface Config {
  /** Default agent for project installs ('prompt' shows selection menu) */
  defaultAgent: Agent | 'prompt';
  /** Agent for global installs */
  globalAgent: Agent;
}

Usage Examples:

import { getConfig, getDefaultAgent, getGlobalAgent } from "@antfu/ni";

// Get full configuration
const config = await getConfig();
console.log(config);
// { defaultAgent: 'npm', globalAgent: 'npm' }

// Get specific agents
const defaultAgent = await getDefaultAgent();
console.log(defaultAgent); // 'npm' | 'yarn' | 'pnpm' | 'bun' | 'prompt'

const globalAgent = await getGlobalAgent();
console.log(globalAgent); // 'npm' | 'yarn' | 'pnpm' | 'bun'

// In programmatic mode, 'prompt' becomes 'npm'
const programmaticAgent = await getDefaultAgent(true);
console.log(programmaticAgent); // Never 'prompt' in programmatic mode

Configuration Sources

Configuration is loaded from multiple sources in order of precedence:

1. Environment Variables

Highest priority configuration source:

# Default agent for project operations
export NI_DEFAULT_AGENT="pnpm"

# Global agent for global installs
export NI_GLOBAL_AGENT="npm"

# Custom config file location
export NI_CONFIG_FILE="$HOME/.config/ni/nirc"

# Auto-install missing package managers
export NI_AUTO_INSTALL="true"

2. Configuration File (.nirc)

Default location: ~/.nirc (or $NI_CONFIG_FILE if set)

Format: INI-style key-value pairs

# ~/.nirc

# Default agent for project installs
# Options: npm, yarn, pnpm, bun, prompt
defaultAgent=pnpm

# Agent for global installs  
# Options: npm, yarn, pnpm, bun
globalAgent=npm

3. Auto-Detection

If no configuration is found, ni will:

Attempt to detect from current project lock files
Fall back to 'prompt' (interactive selection)
Use 'npm' in CI environments or programmatic mode

Configuration File Management

File Locations

// Default configuration paths
const defaultRcPath = "~/.nirc";  // Unix/Linux/macOS
const defaultRcPath = "%USERPROFILE%\\.nirc";  // Windows

// Custom path via environment variable
const customRcPath = process.env.NI_CONFIG_FILE;

File Format

The .nirc file uses INI format:

# Fallback when no lock file is found
# Values: npm, yarn, pnpm, bun, prompt
defaultAgent=prompt

# For global installs (ni -g, nun -g)
# Values: npm, yarn, pnpm, bun  
globalAgent=npm

Creating Configuration

# Create basic configuration
echo "defaultAgent=pnpm" > ~/.nirc
echo "globalAgent=npm" >> ~/.nirc

# Or use custom location
mkdir -p ~/.config/ni
echo "defaultAgent=yarn" > ~/.config/ni/nirc
export NI_CONFIG_FILE="$HOME/.config/ni/nirc"

Environment Variables

All configuration can be controlled via environment variables:

interface EnvironmentVariables {
  /** Custom config file path */
  NI_CONFIG_FILE?: string;
  
  /** Default agent (overrides config file) */
  NI_DEFAULT_AGENT?: Agent;
  
  /** Global agent (overrides config file) */
  NI_GLOBAL_AGENT?: Agent;
  
  /** Auto-install missing package managers */
  NI_AUTO_INSTALL?: 'true' | 'false';
  
  /** CI environment flag (affects prompts) */
  CI?: string;
}

Shell Configuration Examples

Bash/Zsh (.bashrc, .zshrc):

# Set default package manager
export NI_DEFAULT_AGENT="pnpm"
export NI_GLOBAL_AGENT="npm"

# Enable auto-installation
export NI_AUTO_INSTALL="true"

# Custom config location
export NI_CONFIG_FILE="$HOME/.config/ni/nirc"

PowerShell (Microsoft.PowerShell_profile.ps1):

# Set default package manager
$Env:NI_DEFAULT_AGENT = "pnpm"
$Env:NI_GLOBAL_AGENT = "npm"

# Custom config location
$Env:NI_CONFIG_FILE = "C:\Users\$Env:USERNAME\.config\ni\nirc"

Windows CMD:

set NI_DEFAULT_AGENT=pnpm
set NI_GLOBAL_AGENT=npm
set NI_CONFIG_FILE=%USERPROFILE%\.config\ni\nirc

Agent Selection Behavior

Default Agent Selection

Environment Variable: NI_DEFAULT_AGENT if set
Auto-Detection: Package manager from lock files
Config File: defaultAgent from .nirc
Fallback: 'prompt' (interactive) or 'npm' (CI/programmatic)

Global Agent Selection

Environment Variable: NI_GLOBAL_AGENT if set
Config File: globalAgent from .nirc
Fallback: 'npm'

Prompt Behavior

When defaultAgent is set to 'prompt':

// Interactive selection in non-CI environments
const agents = ['npm', 'yarn', 'pnpm', 'bun'];
// User selects from menu

// Automatic fallback in CI or programmatic mode
const agent = 'npm'; // Default fallback

Advanced Configuration

Project-Specific Detection

ni automatically detects project package managers:

// Detection priority order:
// 1. packageManager field in package.json
// 2. Lock file presence:
//    - package-lock.json → npm
//    - yarn.lock → yarn  
//    - pnpm-lock.yaml → pnpm
//    - bun.lock/bun.lockb → bun
// 3. Configuration fallback

Volta Integration

When Volta is detected, commands are automatically wrapped:

interface VoltaIntegration {
  /** Enable Volta detection (default: true) */
  detectVolta?: boolean;
}

// Example: ni install becomes volta run npm install

CI Environment Handling

Special behavior in CI environments:

// When process.env.CI is set:
// - No interactive prompts
// - Auto-install prompts become errors
// - 'prompt' defaults to 'npm'
// - Reduced console output

Configuration Examples

Development Team Setup

# ~/.nirc for consistent team setup
defaultAgent=pnpm
globalAgent=npm

# .bashrc for team consistency
export NI_DEFAULT_AGENT="pnpm"
export NI_GLOBAL_AGENT="npm"  
export NI_AUTO_INSTALL="true"

Multi-Project Developer

# Different agents per project type
alias ni-npm='NI_DEFAULT_AGENT=npm ni'
alias ni-pnpm='NI_DEFAULT_AGENT=pnpm ni'
alias ni-yarn='NI_DEFAULT_AGENT=yarn ni'

CI/CD Pipeline

# GitHub Actions example
env:
  NI_DEFAULT_AGENT: "npm"
  NI_AUTO_INSTALL: "false"
  CI: "true"

PowerShell Conflicts

Windows PowerShell has a built-in ni alias. To resolve:

# Remove PowerShell's ni alias
Remove-Item Alias:ni -Force -ErrorAction Ignore

# Add to profile for persistence
if (-not (Test-Path $profile)) {
  New-Item -ItemType File -Path (Split-Path $profile) -Force -Name (Split-Path $profile -Leaf)
}

$profileEntry = 'Remove-Item Alias:ni -Force -ErrorAction Ignore'
$profileContent = Get-Content $profile
if ($profileContent -notcontains $profileEntry) {
  ("`n" + $profileEntry) | Out-File $profile -Append -Force -Encoding UTF8
}