Skip to main content

Python CLI

toothfairy-cli@latest…

The Python CLI (toothfairy-cli) exposes 70 commands covering the core platform surface. This page walks through the most common workflows; for the complete flag-by-flag reference, see the Python CLI command reference.

Install:

pip install toothfairy-cli
toothfairy configure --api-key YOUR_KEY --workspace-id YOUR_WORKSPACE

Send a message to an agent​

toothfairy send "Hello" --agent-id AGENT_ID
# continue an existing chat
toothfairy send "Follow-up" --agent-id AGENT_ID --chat-id CHAT_ID

Stream a response​

toothfairy send-stream "Explain RAG" --agent-id AGENT_ID

Predictions​

toothfairy predict --model sorcerer --message "Summarise this" \
  --max-tokens 256 --temperature 0.3
predict requires --model

Unlike the Node CLI, the Python predict command requires the --model flag explicitly.

Agents CRUD​

toothfairy create-agent --label "Support" --mode retriever \
  --interpolation-string "You are a helpful assistant." --goals "Help customers"
toothfairy list-agents
toothfairy get-agent AGENT_ID
toothfairy update-agent AGENT_ID --label "Support v2"
toothfairy delete-agent AGENT_ID

Documents​

toothfairy upload ./report.pdf
toothfairy get-doc DOC_ID
toothfairy delete-doc DOC_ID
toothfairy search "How do I configure SSO?"

Scheduled jobs & triggers​

toothfairy create-scheduled-job --agent-id AGENT_ID --frequency daily --prompt "Daily summary"
toothfairy list-scheduled-jobs
toothfairy pause-scheduled-job JOB_ID

toothfairy create-trigger --agent-id AGENT_ID --name "Webhook trigger" \
  --event-source-type EXTERNAL
toothfairy list-triggers

Benchmarks​

toothfairy create-benchmark --name "Retrieval quality"
toothfairy run-benchmark BENCHMARK_ID
toothfairy list-benchmark-runs

Parity gaps vs the Node CLI​

The Python CLI does not implement voice, entities, folders, prompts, members, sites, hooks, or secrets commands. For those resources, use the Node CLI or the Python SDK.

Tips​

  • Add --help to any command for full flags, e.g. toothfairy create-agent --help.
  • The shorter alias tf works everywhere: tf list-agents.