# 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:

```bash
brew install python@3.12
```

If you don't have Homebrew, install it first:
```bash
/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:
```bash
sudo apt update
sudo apt install python3.12 python3-pip
```

### Verify Python Installation

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

```bash
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

```bash
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)

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

### Verify Node.js Installation

```bash
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:

```bash
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):

```bash
# 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)

```cmd
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:

```bash
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:

```bash
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:

```bash
tfcode tools list
```

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

---

## Step 9: Start Coding!

Now you're ready to use tfcode:

```bash
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:
```bash
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*