better-tinker 0.5.0

Tinker CLI wrapper and bridge

Better Tinker

A beautiful terminal interface for the Tinker API, built with Bubble Tea.

Features

• 🚀 Training Runs - View and manage your training runs with expandable tree view
• 💾 Checkpoints - Browse, publish/unpublish, and delete model checkpoints
• 📊 Usage Statistics - View your API usage and quotas
• ⚙️ Settings - Configure API key (stored in local config file)
• ✨ Interactive UI - Beautiful dark theme with keyboard navigation

Quick Start

Option 1: Using uv/uvx (Recommended)

# Install uv if you don't have it
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Run directly (downloads and runs in isolated environment)
uvx better-tinker

Option 2: Using pip

pip install better-tinker
better-tinker

Architecture

This CLI uses a Python bridge server to communicate with the Tinker API. The bridge is started automatically when you run better-tinker.

┌─────────────┐   Authorization Header   ┌─────────────────┐     gRPC-Web    ┌─────────────┐
│  Go CLI     │ ────────────────────────► │  Python Bridge  │ ──────────────► │ Tinker API  │
│ (Bubble Tea)│   Bearer <api_key>       │    (FastAPI)    │                 │             │
└─────────────┘                          └─────────────────┘                 └─────────────┘

Configuration

Option 1: Use the Settings Menu (Recommended)

The easiest way to configure your API key is through the CLI itself:

1. Run better-tinker
2. Select Settings from the menu
3. Select API Key and enter your key
4. The key is stored in a local config file:
   • Windows: %APPDATA%\tinker-cli\config.json
   • macOS/Linux: ~/.config/tinker-cli/config.json

Option 2: Environment Variable

Set your Tinker API key as an environment variable:

# Linux/macOS
export TINKER_API_KEY="your-api-key-here"

# Windows (PowerShell)
$env:TINKER_API_KEY="your-api-key-here"

# Windows (CMD)
set TINKER_API_KEY=your-api-key-here

# Then run
better-tinker

Note: Environment variables take precedence over stored credentials.

Persistent Environment Variable (Recommended for uvx)

If you use uvx, setting the environment variable in your shell config is the most reliable method:

macOS/Linux (bash/zsh):

echo 'export TINKER_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell profile):

# Add to your PowerShell profile
Add-Content $PROFILE 'setx TINKER_API_KEY "your-api-key-here"'

Keyboard Controls

Key	Action
↑/k	Move up
↓/j	Move down
Enter	Select / Confirm / Edit
Space	Expand/collapse training run
r	Refresh data
p	Publish/Unpublish checkpoint
d	Delete checkpoint / Delete API key (in Settings)
Esc	Go back / Cancel editing
q	Quit

Environment Variables

Variable	Description	Default
TINKER_API_KEY	Your Tinker API key	(from config)
TINKER_BRIDGE_URL	Custom bridge server URL	http://127.0.0.1:8765
TINKER_BRIDGE_PORT	Bridge server port	8765
TINKER_BRIDGE_HOST	Bridge server host	127.0.0.1

Troubleshooting

"API key required" error

Set your API key using one of these methods:

1. Via Settings menu (recommended):

   better-tinker
   # Navigate to Settings > API Key
   

2. Via environment variable:

   export TINKER_API_KEY="your-api-key-here"
   better-tinker
   

"Tinker SDK not installed" error

This usually means the Python environment is missing dependencies. Try:

# Reinstall with fresh environment
uvx --refresh better-tinker

# Or with pip
pip install --upgrade better-tinker tinker

"Bridge server not running" error

The bridge should start automatically. If it fails:

1. Check if port 8765 is already in use
2. Try manually starting the bridge:

   python -m better_tinker.bridge.server
   

API Documentation

When the bridge server is running, you can access the interactive API documentation at:

• Swagger UI: http://127.0.0.1:8765/docs
• ReDoc: http://127.0.0.1:8765/redoc

Development

Build from source

git clone https://github.com/mohaddz/better-tinker.git
cd better-tinker

# Build Go binaries for all platforms
python build_binaries.py

# Install in development mode
pip install -e .

# Run
better-tinker

Project Structure

better-tinker/
├── main.go                 # Go CLI entry point (thin wrapper around internal/tui)
├── better_tinker/
│   ├── wrapper.py          # Python wrapper (starts bridge + Go CLI)
│   └── bridge/
│       └── server.py       # FastAPI bridge server
├── internal/
│   ├── api/
│   │   ├── client.go       # REST API client (calls bridge)
│   │   └── types.go        # API response types
│   ├── config/
│   │   └── config.go       # Configuration / credential storage
│   ├── tui/
│   │   ├── program.go      # Bubble Tea program wiring
│   │   ├── model.go        # App state + initial model
│   │   ├── update.go       # Update loop + navigation logic
│   │   ├── views.go        # View rendering
│   │   ├── commands.go     # Async commands (API calls)
│   │   ├── types.go        # Msg/types used by the TUI
│   │   ├── layout.go       # Layout helpers
│   │   ├── util.go         # Small helpers
│   │   └── menu_delegate.go # Custom menu renderer
│   └── ui/
│       ├── styles.go       # Lip Gloss styles
├── build_binaries.py       # Cross-compilation script
├── pyproject.toml          # Python package config
└── go.mod                  # Go module config

Tech Stack

Go CLI

• TUI Framework: Bubble Tea
• Components: Bubbles
• Styling: Lip Gloss

Python Bridge

• Web Framework: FastAPI
• ASGI Server: Uvicorn
• Tinker SDK: Official Python SDK for Tinker API

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.