Skip to main content

CLI overview

ToothFairyAI ships two command-line interfaces that expose the toothfairy binary (with a shorter tf alias):

  • Node.js CLI — npm install -g @toothfairyai/cli
  • Python CLI — pip install toothfairy-cli

Both CLIs are flat (no nested subcommand groups): every action is a top-level command like toothfairy create-agent or toothfairy predict.

Configuration​

Credentials are resolved in this priority order:

  1. Per-invocation flags: --apiKey / --workspaceid (Node) or --api-key / --workspace-id (Python).
  2. Environment variables: TF_API_KEY and TF_WORKSPACE_ID.
  3. A saved config file created by toothfairy configure.
# interactive setup (writes a config file)
toothfairy configure --api-key YOUR_KEY --workspace-id YOUR_WORKSPACE

# or just export env vars
export TF_API_KEY=YOUR_KEY
export TF_WORKSPACE_ID=YOUR_WORKSPACE

Output​

Commands print human-readable output by default. For scripting, most commands accept a --json flag (Node) or return JSON when piped, so you can feed results into jq or other tools.

Command surface parity​

The two CLIs share the core command set (agents, chat, search, documents, channels, connections, triggers, scheduled jobs, benchmarks, etc.). There are parity differences to be aware of:

CapabilityNode CLIPython CLI
Agents, chat, search, documents✅✅
Voice (speech/audio)✅❌
Entities, folders, prompts✅❌
Members, sites, hooks, secrets✅❌
Streams✅✅
Fine-tuning❌❌ (use the Python SDK)

For the exhaustive, auto-generated list of every command with its flags and arguments, see:

Common workflows​

The per-CLI overview pages walk through the most common workflows: