Config

TF Code uses JSON config files merged in precedence order. Profile credentials and environment variables override file-based settings.

Interactive Setup

The recommended way to get started:

tfcode setup

This prompts for profile name, workspace ID, API key, and region, then saves them as a named profile.

Profiles

Profiles store multiple sets of ToothFairyAI credentials so you can switch between workspaces instantly.

Create

tfcode setup
# Prompts for: profile name, workspace ID, API key, region

Non-interactive:

tfcode setup --profile dev --workspace-id dev-ws-456 --api-key dev-key-xxx --region dev --name dev

Switch

tfcode profile prod
tfcode profile
# Current profile: prod
#
# Available profiles:
#  *  prod
#     dev

Use in commands

tfcode -p prod run "Deploy to production"
TF_PROFILE=prod tfcode run "Force prod workspace"

Storage

Profiles are stored in ~/.local/share/tfcode/.tfcode/profiles.json:

{
  "default": "prod",
  "profiles": {
    "prod": {
      "api_key": "prod-key-xxx",
      "workspace_id": "prod-ws-123",
      "region": "au"
    },
    "dev": {
      "api_key": "dev-key-yyy",
      "workspace_id": "dev-ws-456",
      "region": "dev"
    }
  }
}

Profiles replace the legacy credentials.json. TF Code automatically migrates it on first profile command.

Regions

Region	Base URL	Streaming URL
dev	ai.toothfairylab.link	ais.toothfairylab.link
au	ai.toothfairyai.com	ais.toothfairyai.com
eu	ai.eu.toothfairyai.com	ais.eu.toothfairyai.com
us	ai.us.toothfairyai.com	ais.us.toothfairyai.com

Config File Locations

Config sources are loaded in order of increasing priority (later overrides earlier):

1. Global config — ~/.config/tfcode/tfcode.json
2. Custom config — OPENCODE_CONFIG env var path
3. Project config — tfcode.json in project root
4. .tfcode/tfcode.json in project root
5. Inline config — OPENCODE_CONFIG_CONTENT env var
6. Active profile — set via tfcode profile <name> or --profile / TF_PROFILE
7. Environment variables — TF_WORKSPACE_ID, TF_API_KEY, TF_REGION

Files are merged together, not replaced. Non-conflicting settings from all sources are preserved.

Project config example

.tfcode/tfcode.json:

{
  "toothfairy": {
    "workspace_id": "your-workspace-id",
    "api_key": "your-api-key",
    "region": "au"
  },
  "model": "toothfairyai/mystica",
  "default_agent": "build"
}

Environment Variables

Variable	Description
TF_WORKSPACE_ID	ToothFairyAI workspace ID
TF_API_KEY	ToothFairyAI API key
TF_REGION	ToothFairyAI region: dev, au, eu, us
TF_PROFILE	Profile name to use (overrides default profile)
TFCODE_SERVER_PASSWORD	HTTP basic auth password for server mode
TFCODE_SERVER_USERNAME	HTTP basic auth username (default: tfcode)
OPENCODE_CONFIG	Path to custom config file
OPENCODE_CONFIG_CONTENT	Inline config content (highest priority)

Validate

tfcode validate
tfcode validate --profile prod

Server Config

The server block controls the HTTP server:

{
  "server": {
    "port": 4096,
    "hostname": "127.0.0.1",
    "mdns": false,
    "mdnsDomain": "tfcode.local",
    "cors": ["https://app.example.com"]
  }
}

Logging

tail -f ~/.local/share/tfcode/log/dev.log
tfcode --log-level DEBUG

Levels: DEBUG, INFO, WARN, ERROR.

CLI Commands Reference

Top-level

Command	Description
tfcode	Start interactive session
tfcode run <prompt>	Execute a single task and exit
tfcode serve	Start headless HTTP server
tfcode web	Start server and open web interface
tfcode attach <url>	Attach TUI to a running server

Setup & credentials

Command	Description
tfcode setup	Interactive credential setup (creates a profile)
tfcode validate	Validate credentials (--profile <name> for specific)
tfcode profile	Show current profile and list all
tfcode profile <name>	Switch to a different profile
tfcode sync	Sync workspace tools metadata
tfcode providers list	List available providers
tfcode models [provider]	List available models (optional provider filter)
tfcode models --verbose	List models with metadata
tfcode models --refresh	Refresh the models cache

MCP

Command	Description
tfcode mcp list	List MCP servers and tools
tfcode mcp add	Add a local MCP server
tfcode mcp auth	Authenticate with OAuth MCP server
tfcode mcp logout	Logout from MCP server

Other

Command	Description
tfcode -p/--profile	Switch profile per command
tfcode --log-level	Set log level
tfcode --version	Show version
tfcode --help	Show all commands

Chat commands (interactive)

Command	Description
/compact [instructions]	Compact context with preservation hints
/help	Show available commands