tf_code/docs/setup-guide.md

tfcode Setup Guide for New Users

Time required: ~10 minutes

This guide will walk you through installing tfcode step by step. No technical experience needed.

---

What You'll Need

1. Python 3.10 or newer (required for ToothFairyAI integration)
2. Node.js (required to run tfcode)
3. Your ToothFairyAI credentials (workspace ID and API key)

---

Step 1: Install Python

macOS

1. Open Terminal (press Cmd + Space, type "Terminal", press Enter)
2. Copy and paste this command, then press Enter:

brew install python@3.12

If you don't have Homebrew, install it first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Windows

1. Go to https://python.org/downloads
2. Click "Download Python 3.12" (or latest version)
3. Run the installer
4. Important: Check the box that says "Add Python to PATH"
5. Click "Install Now"

Linux (Ubuntu/Debian)

Open Terminal and run:

sudo apt update
sudo apt install python3.12 python3-pip

Verify Python Installation

Open Terminal (macOS/Linux) or Command Prompt (Windows) and type:

python3 --version

You should see something like: Python 3.12.x

✅ If you see this, Python is installed correctly!

---

Step 2: Install Node.js

macOS

brew install node

Windows

1. Go to https://nodejs.org
2. Download the "LTS" (Long Term Support) version
3. Run the installer with default settings

Linux (Ubuntu/Debian)

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Verify Node.js Installation

node --version

You should see something like: v20.x.x

✅ If you see this, Node.js is installed correctly!

---

Step 3: Install tfcode

Open Terminal (macOS/Linux) or Command Prompt (Windows) and run:

npm install -g tfcode

You'll see output like:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  tfcode - ToothFairyAI's official coding agent
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Found Python 3.12.x (python3)
✓ Python dependencies installed

✓ tfcode installed successfully!

✅ tfcode is now installed!

---

Step 4: Get Your ToothFairyAI Credentials

1. Log in to your ToothFairyAI workspace at https://app.toothfairyai.com
2. Go to Settings → API Keys
3. Copy your Workspace ID and API Key

You'll need these for the next step.

---

Step 5: Configure tfcode

macOS / Linux

Open Terminal and run these commands (replace with your actual credentials):

# Set your credentials
export TF_WORKSPACE_ID="your-workspace-id-here"
export TF_API_KEY="your-api-key-here"
export TF_REGION="au"

# Make them permanent (so you don't have to set them every time)
echo 'export TF_WORKSPACE_ID="your-workspace-id-here"' >> ~/.zshrc
echo 'export TF_API_KEY="your-api-key-here"' >> ~/.zshrc
echo 'export TF_REGION="au"' >> ~/.zshrc

Windows (Command Prompt)

setx TF_WORKSPACE_ID "your-workspace-id-here"
setx TF_API_KEY "your-api-key-here"
setx TF_REGION "au"

Note: Close and reopen Command Prompt after running these commands.

Region Options

• au - Australia (default)
• eu - Europe
• us - United States
• dev - Development (for internal testing)

---

Step 6: Validate Your Setup

Run this command to check everything is working:

tfcode validate

You should see:

Validating ToothFairyAI credentials...
✓ Credentials valid
  Workspace: Your Workspace Name
  ID: your-workspace-id

✅ If you see this, your credentials are correct!

❌ If you see an error:

• Double-check your Workspace ID and API Key
• Make sure you copied them completely (no extra spaces)
• Try a different region (au, eu, or us)

---

Step 7: Sync Your Tools

Run this command to sync tools from your ToothFairyAI workspace:

tfcode sync

You should see:

Syncing tools from ToothFairyAI workspace...
✓ Synced X tools

By type:
  api_function: X

---

Step 8: View Your Tools

List all synced tools:

tfcode tools list

You'll see all the tools available from your workspace.

---

Step 9: Start Coding!

Now you're ready to use tfcode:

tfcode

This opens the tfcode terminal interface where you can:

• Chat with the AI
• Ask it to write code
• Use your synced tools

---

Quick Reference

Command	What it does
tfcode validate	Check your credentials work
tfcode sync	Sync tools from your workspace
tfcode tools list	Show all your synced tools
tfcode tools list --type mcp	Show only MCP servers
tfcode tools credentials <name> --set	Add an API key for a tool
tfcode	Start the coding assistant

---

Troubleshooting

"Python 3.10+ is required but not found"

Solution: Install Python (see Step 1)

"Failed to validate: Invalid API key"

Solution:

1. Go to ToothFairyAI Settings → API Keys
2. Generate a new API key
3. Update your credentials:
   • macOS/Linux: Edit ~/.zshrc
   • Windows: Run the setx commands again

"Failed to validate: Workspace not found"

Solution: Check your Workspace ID is correct

"Failed to validate: Connection test failed"

Solution: Try a different region:

• au - Australia
• eu - Europe
• us - United States

Update with:

export TF_REGION="eu"  # or us, au

"command not found: tfcode"

Solution:

1. Make sure you installed tfcode: npm install -g tfcode
2. Restart your terminal

"npm: command not found"

Solution: Install Node.js (see Step 2)

---

Need Help?

• Documentation: https://toothfairyai.com/developers/tfcode
• Support: Contact ToothFairyAI support
• Issues: Report bugs at https://github.com/ToothFairyAI/tfcode/issues

---

What's Next?

1. Read the docs: https://toothfairyai.com/developers/tfcode
2. Try a simple task: tfcode then ask "Create a simple Node.js HTTP server"
3. Configure MCP servers: Add MCP servers to ~/.tfcode/tfcode.json
4. Set up API keys: tfcode tools credentials <tool-name> --set

---

Last updated: 2026-03-24