Python CLI command reference

toothfairy-cli@latest…

Every command below is a subcommand of toothfairy (alias tf). Global credentials come from TF_API_KEY / TF_WORKSPACE_ID or toothfairy configure.

70 commands.

Index

Command	Summary
billing-month-costs	Get monthly usage and cost information.
cancel-benchmark-run	Cancel a running benchmark.
chat	Get details of a specific chat.
chats	List all chats in the workspace.
config-show	Show current configuration.
configure	Configure ToothFairy CLI credentials and settings.
create-agent	Create a new agent.
create-agent-function	Create a new agent function.
create-authorization	Create a new authorization.
create-benchmark	Create a new benchmark.
create-channel	Create a new communication channel.
create-connection	Create a new connection (hosting configuration).
create-scheduled-job	Create a new scheduled job (cron job).
create-trigger	Create a new event-driven agent trigger.
delete-agent	Delete an agent.
delete-agent-function	Delete an agent function.
delete-authorization	Delete an authorization.
delete-benchmark	Delete a benchmark.
delete-channel	Delete a channel.
delete-connection	Delete a connection.
delete-scheduled-job	Delete a scheduled job.
delete-trigger	Delete a trigger.
download	Download a file from ToothFairy workspace.
get-agent	Get details of a specific agent.
get-agent-function	Get details of a specific agent function.
get-authorization	Get details of a specific authorization.
get-benchmark	Get details of a specific benchmark.
get-benchmark-run	Get a benchmark run by ID with score and metadata.
get-channel	Get details of a specific channel.
get-charting-settings	Get charting settings for the workspace.
get-connection	Get details of a specific connection (hosting configuration).
get-dictionary	Get details of a specific dictionary entry.
get-embedding	Get details of a specific embedding.
get-embeddings-settings	Get embeddings settings for the workspace.
get-scheduled-job	Get details of a specific scheduled job.
get-scheduled-jobs-by-status	Get scheduled jobs by status.
get-stream	Get details of a specific stream.
get-trigger	Get a specific trigger by ID.
help-guide	Show detailed help and usage examples.
list-agent-functions	List all agent functions.
list-agents	List all agents.
list-authorizations	List all authorizations.
list-benchmark-runs	List benchmark runs for the workspace.
list-benchmarks	List all benchmarks.
list-channels	List all channels.
list-connections	List all connections (hosting configurations).
list-dictionaries	List all dictionary entries.
list-scheduled-jobs	List all scheduled jobs.
list-streams	List all streams.
list-triggers	List all triggers in the workspace.
pause-scheduled-job	Pause a scheduled job.
pause-trigger	Pause (disarm) a trigger.
predict	Generate streaming AI predictions (OpenAI-compatible) from a ToothFairyAI model.
resume-scheduled-job	Resume a paused scheduled job.
resume-trigger	Resume (arm) a paused trigger.
run-benchmark	Start a benchmark run to evaluate an agent.
search	Search for documents in the knowledge hub.
send	Send a message to a ToothFairyAI agent.
send-stream	Send a message to a ToothFairyAI agent with real-time streaming response.
update-agent	Update an existing agent.
update-agent-function	Update an existing agent function.
update-authorization	Update an existing authorization.
update-benchmark	Update an existing benchmark.
update-channel	Update an existing channel.
update-charting-settings	Update charting settings for the workspace.
update-connection	Update an existing connection (hosting configuration).
update-embeddings-settings	Update embeddings settings for the workspace.
update-scheduled-job	Update an existing scheduled job.
update-trigger	Update an existing trigger.
upload	Upload a file to ToothFairy workspace.

billing-month-costs

Get monthly usage and cost information.

Arguments

Name	Required	Description
<month>	yes	—
<year>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy billing-month-costs <month> <year>

cancel-benchmark-run

Cancel a running benchmark.

Arguments

Name	Required	Description
<run_id>	yes	—

Options

Flag	Required	Default	Description
--confirm	no	False	Skip confirmation prompt
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy cancel-benchmark-run <run_id>

chat

Get details of a specific chat.

Arguments

Name	Required	Description
<chat_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format

toothfairy chat <chat_id>

chats

List all chats in the workspace.

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format

toothfairy chats

config-show

Show current configuration.

toothfairy config-show

configure

Configure ToothFairy CLI credentials and settings.

Options

Flag	Required	Default	Description
--base-url	no	https://api.toothfairyai.com	ToothFairy API base URL
--ai-url	no	https://ai.toothfairyai.com	ToothFairyAI URL
--ai-stream-url	no	https://ais.toothfairyai.com	ToothFairyAI Streaming URL
--api-key	yes	Sentinel.UNSET	API key
--workspace-id	yes	Sentinel.UNSET	Workspace ID
--config-path	no	Sentinel.UNSET	Path to save config file

toothfairy configure

create-agent

Create a new agent.

Options

Flag	Required	Default	Description
--label	no	Sentinel.UNSET	Agent label
--description	no	Sentinel.UNSET	Agent description
--emoji	no	Sentinel.UNSET	Agent emoji
--mode	no	Sentinel.UNSET	Agent mode
--agent-type	no	Sentinel.UNSET	Agent type (Chatbot
--llm-provider	no	Sentinel.UNSET	LLM provider
--llm-base-model	no	Sentinel.UNSET	LLM base model
--reasoning-mode	no	Sentinel.UNSET	Reasoning mode (auto
--reasoning-effort	no	Sentinel.UNSET	Reasoning effort (none
--fn-reasoning-effort	no	Sentinel.UNSET	Function reasoning effort
--reasoning-budget	no	Sentinel.UNSET	Reasoning budget
--voice-name	no	Sentinel.UNSET	Voice name for voice mode
--voice-sensitivity	no	Sentinel.UNSET	Voice sensitivity
--stt-model	no	Sentinel.UNSET	Speech-to-text model
--tts-model	no	Sentinel.UNSET	Text-to-speech model
--llm-voice-model	no	Sentinel.UNSET	LLM voice model
--default-voice-language	no	Sentinel.UNSET	Default voice language
--department	no	Sentinel.UNSET	Department
--temperature	no	Sentinel.UNSET	Temperature (0.0-2.0)
--max-tokens	no	Sentinel.UNSET	Max tokens
--top-k	no	Sentinel.UNSET	Top K for retrieval
--doc-top-k	no	Sentinel.UNSET	Doc top K
--max-history	no	Sentinel.UNSET	Max conversation history
--allow-internet-search	no	False	Allow internet search
--allow-images-upload	no	False	Allow image uploads
--allow-videos-upload	no	False	Allow video uploads
--allow-audios-upload	no	False	Allow audio uploads
--allow-docs-upload	no	False	Allow document uploads
--allow-images-generation	no	False	Allow image generation
--agentic-rag	no	False	Enable agentic RAG
--re-rank	no	False	Enable re-ranking
--rag-search-strategy	no	Sentinel.UNSET	RAG search strategy
--min-retrieval-score	no	Sentinel.UNSET	Minimum retrieval score
--has-math	no	False	Enable math capabilities
--has-code	no	False	Enable code capabilities
--has-computer	no	False	Enable computer use capabilities
--has-ner	no	False	Enable NER capabilities
--canvas-enabled	no	False	Enable canvas
--enable-json-output	no	False	Enable JSON output
--force-json-output	no	False	Force JSON output
--hide-reasoning	no	False	Hide reasoning from output
--show-citations	no	False	Show citations
--ephemeral-agent	no	False	Mark as ephemeral agent
--parent-agent-id	no	Sentinel.UNSET	Parent agent ID
--agents-pool	no	Sentinel.UNSET	Comma-separated agent IDs for agents pool
--mcps	no	Sentinel.UNSET	Comma-separated MCP IDs
--max-planning-steps	no	Sentinel.UNSET	Max planning steps
--max-browser-steps	no	Sentinel.UNSET	Max browser steps
--custom-code-execution-environments	no	Sentinel.UNSET	Comma-separated custom code execution environment IDs
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy create-agent

create-agent-function

Create a new agent function.

Options

Flag	Required	Default	Description
--name	yes	Sentinel.UNSET	Function name
--description	yes	Sentinel.UNSET	Function description
--url	no	Sentinel.UNSET	Function URL
--request-type	no	Sentinel.UNSET	Request type
--authorisation-type	no	Sentinel.UNSET	Authorisation type
--authorisation-key	no	Sentinel.UNSET	Authorisation key
--authorisation-id	no	Sentinel.UNSET	Authorisation ID
--parameters	no	Sentinel.UNSET	Parameters as JSON
--model	no	Sentinel.UNSET	Model to use
--scope	no	Sentinel.UNSET	Function scope
--json-path-extractor	no	Sentinel.UNSET	JSON path extractor
--headers	no	Sentinel.UNSET	Headers as JSON
--static-args	no	Sentinel.UNSET	Static args as JSON
--custom-execution-code	no	Sentinel.UNSET	Custom execution code
--is-mcp-server	no	False	Is MCP server
--is-callback-fn	no	False	Is callback function
--is-database-script	no	False	Is database script
--is-html-fn	no	False	Is HTML function
--is-chat-fn	no	False	Is chat function
--is-hand-off-fn	no	False	Is hand-off function
--is-code-template	no	False	Is code template
--is-agent-skill	no	False	Is agent skill
--code-execution-environment-id	no	Sentinel.UNSET	Code execution environment ID
--on-fn-call	no	Sentinel.UNSET	On function call config as JSON
--hand-off-agent	no	Sentinel.UNSET	Hand-off agent ID
--hand-off-to-original-agent-on-completion	no	False	Hand off to original agent on completion
--hand-off-to-original-agent-on-failure	no	False	Hand off to original agent on failure
--hand-off-agent-on-completion	no	Sentinel.UNSET	Hand-off agent ID on completion
--hand-off-agent-on-failure	no	Sentinel.UNSET	Hand-off agent ID on failure
--agent-skill-script	no	Sentinel.UNSET	Agent skill script
--chat-script	no	Sentinel.UNSET	Chat script
--chat-action	no	Sentinel.UNSET	Chat action (suggestion
--html-url	no	Sentinel.UNSET	HTML URL
--html-script	no	Sentinel.UNSET	HTML script
--is-html-redirect-fn	no	False	Is HTML redirect function
--html-form-on-successful-submit-message	no	Sentinel.UNSET	HTML form success message
--html-form-on-failed-submit-message	no	Sentinel.UNSET	HTML form failure message
--db-schema-metadata	no	Sentinel.UNSET	DB schema metadata as JSON
--pre-execution-script	no	Sentinel.UNSET	Pre-execution script
--post-execution-script	no	Sentinel.UNSET	Post-execution script
--db-script	no	Sentinel.UNSET	Database script
--db-connection-id	no	Sentinel.UNSET	Database connection ID
--pre-execution-fn-id	no	Sentinel.UNSET	Pre-execution function ID
--pre-execution-mapping	no	Sentinel.UNSET	Pre-execution mapping as JSON
--oauth-connection-id	no	Sentinel.UNSET	OAuth connection ID
--handed-off-to-human-on-call	no	False	Handed off to human on call
--graphql-query	no	Sentinel.UNSET	GraphQL query
--graphql-mutation	no	Sentinel.UNSET	GraphQL mutation
--graphql-operation-name	no	Sentinel.UNSET	GraphQL operation name
--users-to-hand-off-to	no	Sentinel.UNSET	Comma-separated user IDs to hand off to
--depends-on-before-execution	no	Sentinel.UNSET	Comma-separated function IDs to depend on before execution
--depends-on-after-execution	no	Sentinel.UNSET	Comma-separated function IDs to depend on after execution
--is-global	no	False	Is global function
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy create-agent-function

create-authorization

Create a new authorization.

Options

Flag	Required	Default	Description
--name	no	Sentinel.UNSET	Authorization name
--type	no	Sentinel.UNSET	Authorization type
--config	no	Sentinel.UNSET	Authorization configuration (JSON)
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy create-authorization

create-benchmark

Create a new benchmark.

Options

Flag	Required	Default	Description
--name	no	Sentinel.UNSET	Benchmark name
--description	no	Sentinel.UNSET	Benchmark description
--questions	no	Sentinel.UNSET	Questions JSON array
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy create-benchmark

create-channel

Create a new communication channel.

Options

Flag	Required	Default	Description
--name	no	Sentinel.UNSET	Channel name
--channel	no	Sentinel.UNSET	Channel type (sms
--provider	no	Sentinel.UNSET	Service provider
--senderid	no	Sentinel.UNSET	Sender ID
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy create-channel

create-connection

Create a new connection (hosting configuration).

Options

Flag	Required	Default	Description
--name	yes	Sentinel.UNSET	Connection name
--type	yes	Sentinel.UNSET	Hosting type (azure_openai
--endpoint	no	Sentinel.UNSET	Endpoint URL
--model-name	no	Sentinel.UNSET	Model name
--base-model	no	Sentinel.UNSET	Base model
--custom-model	no	False	Is custom model
--api-version	no	Sentinel.UNSET	API version
--token-secret	no	Sentinel.UNSET	Token secret reference
--description	no	Sentinel.UNSET	Connection description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy create-connection

create-scheduled-job

Create a new scheduled job (cron job).

Options

Flag	Required	Default	Description
--name	yes	Sentinel.UNSET	Scheduled job name
--agent-id	yes	Sentinel.UNSET	Agent ID
--custom-prompt-id	no	Sentinel.UNSET	Custom prompt ID
--description	no	Sentinel.UNSET	Job description
--forced-prompt	no	Sentinel.UNSET	Forced prompt text
--frequency	no	Sentinel.UNSET	Frequency (MINUTES
--interval	no	Sentinel.UNSET	Interval
--cron-expression	no	Sentinel.UNSET	Cron expression (for CUSTOM frequency)
--day-of-week	no	Sentinel.UNSET	Day of week (0-6)
--day-of-month	no	Sentinel.UNSET	Day of month (1-31)
--hour	no	Sentinel.UNSET	Hour (0-23)
--minute	no	Sentinel.UNSET	Minute (0-59)
--timezone	no	UTC	Timezone (default: UTC)
--is-active	no	True	Is active
--start-date	no	Sentinel.UNSET	Start date (ISO format)
--end-date	no	Sentinel.UNSET	End date (ISO format)
--execution-config	no	Sentinel.UNSET	Execution config as JSON
--notification-config	no	Sentinel.UNSET	Notification config as JSON
--retry-config	no	Sentinel.UNSET	Retry config as JSON
--metadata	no	Sentinel.UNSET	Metadata as JSON
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy create-scheduled-job

create-trigger

Create a new event-driven agent trigger.

Options

Flag	Required	Default	Description
--name	yes	Sentinel.UNSET	Trigger name
--agent-id	yes	Sentinel.UNSET	Agent ID to invoke
--event-source-type	yes	Sentinel.UNSET	Event source type
--custom-prompt-id	no	Sentinel.UNSET	Custom prompt ID
--description	no	Sentinel.UNSET	Trigger description
--forced-prompt	no	Sentinel.UNSET	Forced prompt text
--event-config	no	Sentinel.UNSET	Event config as JSON string
--is-active	no	True	Arm the trigger (default)
--status	no	Sentinel.UNSET	Trigger status (ARMED
--metadata	no	Sentinel.UNSET	Metadata JSON string
-o, --output	no	text	Output format

toothfairy create-trigger

delete-agent

Delete an agent.

Arguments

Name	Required	Description
<agent_id>	yes	—

Options

Flag	Required	Default	Description
--confirm	no	False	Skip confirmation prompt
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy delete-agent <agent_id>

delete-agent-function

Delete an agent function.

Arguments

Name	Required	Description
<function_id>	yes	—

Options

Flag	Required	Default	Description
--confirm	no	False	Skip confirmation prompt
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy delete-agent-function <function_id>

delete-authorization

Delete an authorization.

Arguments

Name	Required	Description
<auth_id>	yes	—

Options

Flag	Required	Default	Description
--confirm	no	False	Skip confirmation prompt
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy delete-authorization <auth_id>

delete-benchmark

Delete a benchmark.

Arguments

Name	Required	Description
<benchmark_id>	yes	—

Options

Flag	Required	Default	Description
--confirm	no	False	Skip confirmation prompt
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy delete-benchmark <benchmark_id>

delete-channel

Delete a channel.

Arguments

Name	Required	Description
<channel_id>	yes	—

Options

Flag	Required	Default	Description
--confirm	no	False	Skip confirmation prompt
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy delete-channel <channel_id>

delete-connection

Delete a connection.

Arguments

Name	Required	Description
<connection_id>	yes	—

Options

Flag	Required	Default	Description
--confirm	no	False	Skip confirmation prompt
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy delete-connection <connection_id>

delete-scheduled-job

Delete a scheduled job.

Arguments

Name	Required	Description
<job_id>	yes	—

Options

Flag	Required	Default	Description
--confirm	no	False	Skip confirmation prompt
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy delete-scheduled-job <job_id>

delete-trigger

Delete a trigger.

Arguments

Name	Required	Description
<trigger_id>	yes	—

Options

Flag	Required	Default	Description
--confirm	no	False	Skip confirmation prompt
-o, --output	no	text	Output format

toothfairy delete-trigger <trigger_id>

download

Download a file from ToothFairy workspace.

Options

Flag	Required	Default	Description
--filename	yes	Sentinel.UNSET	Name of the file to download (from upload response)
--workspace-id	no	Sentinel.UNSET	Workspace ID (uses config default if not specified)
--context	no	pdf	Download context (default: pdf)
--output-dir	no	./downloads	Output directory
--output-name	no	Sentinel.UNSET	Output filename (defaults to original filename)
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed download information

toothfairy download

get-agent

Get details of a specific agent.

Arguments

Name	Required	Description
<agent_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy get-agent <agent_id>

get-agent-function

Get details of a specific agent function.

Arguments

Name	Required	Description
<function_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy get-agent-function <function_id>

get-authorization

Get details of a specific authorization.

Arguments

Name	Required	Description
<auth_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy get-authorization <auth_id>

get-benchmark

Get details of a specific benchmark.

Arguments

Name	Required	Description
<benchmark_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy get-benchmark <benchmark_id>

get-benchmark-run

Get a benchmark run by ID with score and metadata.

Arguments

Name	Required	Description
<run_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy get-benchmark-run <run_id>

get-channel

Get details of a specific channel.

Arguments

Name	Required	Description
<channel_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy get-channel <channel_id>

get-charting-settings

Get charting settings for the workspace.

Arguments

Name	Required	Description
<settings_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy get-charting-settings <settings_id>

get-connection

Get details of a specific connection (hosting configuration).

Arguments

Name	Required	Description
<connection_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy get-connection <connection_id>

get-dictionary

Get details of a specific dictionary entry.

Arguments

Name	Required	Description
<dictionary_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy get-dictionary <dictionary_id>

get-embedding

Get details of a specific embedding.

Arguments

Name	Required	Description
<embedding_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy get-embedding <embedding_id>

get-embeddings-settings

Get embeddings settings for the workspace.

Arguments

Name	Required	Description
<settings_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy get-embeddings-settings <settings_id>

get-scheduled-job

Get details of a specific scheduled job.

Arguments

Name	Required	Description
<job_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy get-scheduled-job <job_id>

get-scheduled-jobs-by-status

Get scheduled jobs by status.

Arguments

Name	Required	Description
<status>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy get-scheduled-jobs-by-status <status>

get-stream

Get details of a specific stream.

Arguments

Name	Required	Description
<stream_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy get-stream <stream_id>

get-trigger

Get a specific trigger by ID.

Arguments

Name	Required	Description
<trigger_id>	yes	—

Options

Flag	Required	Default	Description
-o, --output	no	text	Output format

toothfairy get-trigger <trigger_id>

help-guide

Show detailed help and usage examples.

toothfairy help-guide

list-agent-functions

List all agent functions.

Options

Flag	Required	Default	Description
--limit	no	50	Maximum number to return
--offset	no	0	Number to skip
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy list-agent-functions

list-agents

List all agents.

Options

Flag	Required	Default	Description
--limit	no	50	Maximum number to return
--offset	no	0	Number to skip
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy list-agents

list-authorizations

List all authorizations.

Options

Flag	Required	Default	Description
--limit	no	50	Maximum number to return
--offset	no	0	Number to skip
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy list-authorizations

list-benchmark-runs

List benchmark runs for the workspace.

Options

Flag	Required	Default	Description
--agent-id	no		Filter by agent ID
--benchmark-id	no		Filter by benchmark ID
--type	no		Filter by type
--status	no		Filter by status
--limit	no	20	Maximum runs to return
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy list-benchmark-runs

list-benchmarks

List all benchmarks.

Options

Flag	Required	Default	Description
--limit	no	50	Maximum number to return
--offset	no	0	Number to skip
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy list-benchmarks

list-channels

List all channels.

Options

Flag	Required	Default	Description
--limit	no	50	Maximum number to return
--offset	no	0	Number to skip
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy list-channels

list-connections

List all connections (hosting configurations).

Options

Flag	Required	Default	Description
--limit	no	50	Maximum number to return
--offset	no	0	Number to skip
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy list-connections

list-dictionaries

List all dictionary entries.

Options

Flag	Required	Default	Description
--limit	no	50	Maximum number to return
--offset	no	0	Number to skip
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy list-dictionaries

list-scheduled-jobs

List all scheduled jobs.

Options

Flag	Required	Default	Description
--limit	no	50	Maximum number to return
--offset	no	0	Number to skip
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy list-scheduled-jobs

list-streams

List all streams.

Options

Flag	Required	Default	Description
--limit	no	50	Maximum number to return
--offset	no	0	Number to skip
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy list-streams

list-triggers

List all triggers in the workspace.

Options

Flag	Required	Default	Description
--limit	no	Sentinel.UNSET	Maximum number of triggers to return
--offset	no	Sentinel.UNSET	Number of triggers to skip
-o, --output	no	text	Output format

toothfairy list-triggers

pause-scheduled-job

Pause a scheduled job.

Arguments

Name	Required	Description
<job_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy pause-scheduled-job <job_id>

pause-trigger

Pause (disarm) a trigger.

Arguments

Name	Required	Description
<trigger_id>	yes	—

Options

Flag	Required	Default	Description
-o, --output	no	text	Output format

toothfairy pause-trigger <trigger_id>

predict

Generate streaming AI predictions (OpenAI-compatible) from a ToothFairyAI model.

Streams the model response in real time, token-by-token, using an OpenAI-compatible chat completions surface.

Arguments

Name	Required	Description
<message>	yes	—

Options

Flag	Required	Default	Description
--model	yes	Sentinel.UNSET	ToothFairyAI model alias (e.g. sorcerer, mystica, z/glm-5p2, kimi-k2p6)
--system	no		Optional system prompt
--message-role	no	user	Role of the message argument (default: user)
--max-tokens	no		Maximum tokens to generate
--temperature	no		Sampling temperature (0-2)
--top-p	no		Nucleus sampling (0-1)
--top-k	no		Top-K sampling
--repetition-penalty	no		Repetition penalty (default 1.0)
--frequency-penalty	no		Frequency penalty (-2 to 2)
--presence-penalty	no		Presence penalty (-2 to 2)
--stop	no		Stop sequence(s), comma-separated
--seed	no		Deterministic sampling seed
--reasoning-mode	no		Reasoning mode
--reasoning-budget	no		Max tokens for thinking
--reasoning-effort	no		Reasoning effort
--response-format	no		OpenAI response_format as JSON string
--verbosity	no		Output verbosity
--user	no		End-user identifier for tracking
--region	no		Provider pool region
--tools	no		OpenAI-format tools JSON string
--tool-choice	no		auto
--workspace-id	no		Override workspace id (deprecated; resolved from api key by default)
--output, -o	no	text	Output format

toothfairy predict <message>

resume-scheduled-job

Resume a paused scheduled job.

Arguments

Name	Required	Description
<job_id>	yes	—

Options

Flag	Required	Default	Description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy resume-scheduled-job <job_id>

resume-trigger

Resume (arm) a paused trigger.

Arguments

Name	Required	Description
<trigger_id>	yes	—

Options

Flag	Required	Default	Description
-o, --output	no	text	Output format

toothfairy resume-trigger <trigger_id>

run-benchmark

Start a benchmark run to evaluate an agent.

Arguments

Name	Required	Description
<benchmark_id>	yes	—
<agent_id>	yes	—

Options

Flag	Required	Default	Description
--type	no	bm	Run type (default: bm)
--mode	no		ABM mode (only for type=abm)
--name	no		Optional name for the run
--passing-score	no		Minimum score to pass (0-1)
--num-questions	no		Number of questions to use
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy run-benchmark <benchmark_id> <agent_id>

search

Search for documents in the knowledge hub.

Arguments

Name	Required	Description
<query>	yes	—

Options

Flag	Required	Default	Description
--top-k, -k	no	10	Number of documents to retrieve (1-50)
--status	no	Sentinel.UNSET	Filter by document status
--document-id	no	Sentinel.UNSET	Search within specific document ID
--topics	no	Sentinel.UNSET	Comma-separated topic IDs to filter by
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed search information

toothfairy search <query>

send

Send a message to a ToothFairyAI agent.

Arguments

Name	Required	Description
<message>	yes	—

Options

Flag	Required	Default	Description
--agent-id	yes	Sentinel.UNSET	Agent ID to send message to
--chat-id	no	Sentinel.UNSET	Existing chat ID to continue conversation
--phone-number	no	Sentinel.UNSET	Phone number for SMS channel
--customer-id	no	Sentinel.UNSET	Customer ID
--provider-id	no	Sentinel.UNSET	SMS provider ID
--customer-info	no	Sentinel.UNSET	Customer info as JSON string
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed response information

toothfairy send <message>

send-stream

Send a message to a ToothFairyAI agent with real-time streaming response.

This command shows the agent's response as it's being generated in real-time, providing live updates on the agent's processing status and streaming text output.

STREAMING BEHAVIOR EXPLAINED:

🔄 STATUS UPDATES: The agent goes through several processing phases:

• 'connected': Connection established with streaming server • 'init': Agent initialization started • 'initial_setup_completed': Basic setup and context loading finished • 'tools_processing_completed': Any required tools/functions processed • 'replying': Agent begins generating the actual response (text starts streaming) • 'updating_memory': Agent updates conversation memory • 'memory_updated': Memory update completed • 'complete': Stream finished successfully

📝 TEXT STREAMING: Once the agent reaches 'replying' status, you'll see the response text being built progressively, word by word, just like ChatGPT or similar AI assistants.

💡 TIP: Use --show-progress to see detailed status updates, or --verbose for full debug info.

Arguments

Name	Required	Description
<message>	yes	—

Options

Flag	Required	Default	Description
--agent-id	yes	Sentinel.UNSET	Agent ID to send message to
--chat-id	no	Sentinel.UNSET	Existing chat ID to continue conversation
--phone-number	no	Sentinel.UNSET	Phone number for SMS channel
--customer-id	no	Sentinel.UNSET	Customer ID
--provider-id	no	Sentinel.UNSET	SMS provider ID
--customer-info	no	Sentinel.UNSET	Customer info as JSON string
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed streaming information
--show-progress	no	False	Show agent processing status updates

toothfairy send-stream <message>

update-agent

Update an existing agent.

Arguments

Name	Required	Description
<agent_id>	yes	—

Options

Flag	Required	Default	Description
--label	no	Sentinel.UNSET	Agent label
--description	no	Sentinel.UNSET	Agent description
--emoji	no	Sentinel.UNSET	Agent emoji
--mode	no	Sentinel.UNSET	Agent mode
--agent-type	no	Sentinel.UNSET	Agent type
--llm-provider	no	Sentinel.UNSET	LLM provider
--llm-base-model	no	Sentinel.UNSET	LLM base model
--reasoning-mode	no	Sentinel.UNSET	Reasoning mode
--reasoning-effort	no	Sentinel.UNSET	Reasoning effort
--fn-reasoning-effort	no	Sentinel.UNSET	Function reasoning effort
--reasoning-budget	no	Sentinel.UNSET	Reasoning budget
--voice-name	no	Sentinel.UNSET	Voice name for voice mode
--voice-sensitivity	no	Sentinel.UNSET	Voice sensitivity
--stt-model	no	Sentinel.UNSET	Speech-to-text model
--tts-model	no	Sentinel.UNSET	Text-to-speech model
--llm-voice-model	no	Sentinel.UNSET	LLM voice model
--default-voice-language	no	Sentinel.UNSET	Default voice language
--department	no	Sentinel.UNSET	Department
--temperature	no	Sentinel.UNSET	Temperature
--max-tokens	no	Sentinel.UNSET	Max tokens
--top-k	no	Sentinel.UNSET	Top K
--doc-top-k	no	Sentinel.UNSET	Doc top K
--max-history	no	Sentinel.UNSET	Max history
--allow-internet-search	no	False	Allow internet search
--allow-images-upload	no	False	Allow image uploads
--allow-videos-upload	no	False	Allow video uploads
--allow-audios-upload	no	False	Allow audio uploads
--allow-docs-upload	no	False	Allow document uploads
--allow-images-generation	no	False	Allow image generation
--agentic-rag	no	False	Enable agentic RAG
--re-rank	no	False	Enable re-ranking
--rag-search-strategy	no	Sentinel.UNSET	RAG search strategy
--min-retrieval-score	no	Sentinel.UNSET	Minimum retrieval score
--has-math	no	False	Enable math capabilities
--has-code	no	False	Enable code capabilities
--has-computer	no	False	Enable computer use
--has-ner	no	False	Enable NER
--canvas-enabled	no	False	Enable canvas
--enable-json-output	no	False	Enable JSON output
--force-json-output	no	False	Force JSON output
--hide-reasoning	no	False	Hide reasoning
--show-citations	no	False	Show citations
--ephemeral-agent	no	False	Mark as ephemeral
--parent-agent-id	no	Sentinel.UNSET	Parent agent ID
--agents-pool	no	Sentinel.UNSET	Comma-separated agent IDs
--mcps	no	Sentinel.UNSET	Comma-separated MCP IDs
--max-planning-steps	no	Sentinel.UNSET	Max planning steps
--max-browser-steps	no	Sentinel.UNSET	Max browser steps
--custom-code-execution-environments	no	Sentinel.UNSET	Comma-separated custom code execution environment IDs
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy update-agent <agent_id>

update-agent-function

Update an existing agent function.

Arguments

Name	Required	Description
<function_id>	yes	—

Options

Flag	Required	Default	Description
--name	no	Sentinel.UNSET	Function name
--description	no	Sentinel.UNSET	Function description
--url	no	Sentinel.UNSET	Function URL
--request-type	no	Sentinel.UNSET	Request type
--authorisation-type	no	Sentinel.UNSET	Authorisation type
--authorisation-key	no	Sentinel.UNSET	Authorisation key
--authorisation-id	no	Sentinel.UNSET	Authorisation ID
--parameters	no	Sentinel.UNSET	Parameters as JSON
--model	no	Sentinel.UNSET	Model to use
--scope	no	Sentinel.UNSET	Function scope
--is-agent-skill	no	False	Is agent skill
--chat-action	no	Sentinel.UNSET	Chat action
--hand-off-agent	no	Sentinel.UNSET	Hand-off agent ID
--hand-off-to-original-agent-on-completion	no	False	Hand off to original agent on completion
--hand-off-to-original-agent-on-failure	no	False	Hand off to original agent on failure
--chat-script	no	Sentinel.UNSET	Chat script
--agent-skill-script	no	Sentinel.UNSET	Agent skill script
--db-connection-id	no	Sentinel.UNSET	Database connection ID
--graphql-query	no	Sentinel.UNSET	GraphQL query
--graphql-mutation	no	Sentinel.UNSET	GraphQL mutation
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy update-agent-function <function_id>

update-authorization

Update an existing authorization.

Options

Flag	Required	Default	Description
--id	no	Sentinel.UNSET	Authorization ID
--name	no	Sentinel.UNSET	Authorization name
--type	no	Sentinel.UNSET	Authorization type
--config	no	Sentinel.UNSET	Authorization configuration (JSON)
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy update-authorization

update-benchmark

Update an existing benchmark.

Options

Flag	Required	Default	Description
--id	no	Sentinel.UNSET	Benchmark ID
--name	no	Sentinel.UNSET	Benchmark name
--description	no	Sentinel.UNSET	Benchmark description
--questions	no	Sentinel.UNSET	Questions JSON array
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy update-benchmark

update-channel

Update an existing channel.

Options

Flag	Required	Default	Description
--id	no	Sentinel.UNSET	Channel ID
--name	no	Sentinel.UNSET	Channel name
--channel	no	Sentinel.UNSET	Channel type
--provider	no	Sentinel.UNSET	Service provider
--senderid	no	Sentinel.UNSET	Sender ID
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy update-channel

update-charting-settings

Update charting settings for the workspace.

Arguments

Name	Required	Description
<settings_id>	yes	—

Options

Flag	Required	Default	Description
--config	no	Sentinel.UNSET	Settings configuration (JSON)
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy update-charting-settings <settings_id>

update-connection

Update an existing connection (hosting configuration).

Arguments

Name	Required	Description
<connection_id>	yes	—

Options

Flag	Required	Default	Description
--name	no	Sentinel.UNSET	Connection name
--type	no	Sentinel.UNSET	Hosting type
--endpoint	no	Sentinel.UNSET	Endpoint URL
--model-name	no	Sentinel.UNSET	Model name
--base-model	no	Sentinel.UNSET	Base model
--custom-model	no	False	Is custom model
--api-version	no	Sentinel.UNSET	API version
--token-secret	no	Sentinel.UNSET	Token secret reference
--description	no	Sentinel.UNSET	Connection description
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy update-connection <connection_id>

update-embeddings-settings

Update embeddings settings for the workspace.

Arguments

Name	Required	Description
<settings_id>	yes	—

Options

Flag	Required	Default	Description
--config	no	Sentinel.UNSET	Settings configuration (JSON)
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy update-embeddings-settings <settings_id>

update-scheduled-job

Update an existing scheduled job.

Arguments

Name	Required	Description
<job_id>	yes	—

Options

Flag	Required	Default	Description
--name	no	Sentinel.UNSET	Job name
--description	no	Sentinel.UNSET	Job description
--forced-prompt	no	Sentinel.UNSET	Forced prompt text
--frequency	no	Sentinel.UNSET	Frequency
--interval	no	Sentinel.UNSET	Interval
--cron-expression	no	Sentinel.UNSET	Cron expression
--hour	no	Sentinel.UNSET	Hour
--minute	no	Sentinel.UNSET	Minute
--timezone	no	Sentinel.UNSET	Timezone
--is-active	no	False	Is active
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed information

toothfairy update-scheduled-job <job_id>

update-trigger

Update an existing trigger.

Arguments

Name	Required	Description
<trigger_id>	yes	—

Options

Flag	Required	Default	Description
--name	no	Sentinel.UNSET	Trigger name
--agent-id	no	Sentinel.UNSET	Agent ID
--description	no	Sentinel.UNSET	Description
--forced-prompt	no	Sentinel.UNSET	Forced prompt text
--is-active	no	Sentinel.UNSET	Arm/disarm
--status	no	Sentinel.UNSET	Status (ARMED
--metadata	no	Sentinel.UNSET	Metadata JSON string
-o, --output	no	text	Output format

toothfairy update-trigger <trigger_id>

upload

Upload a file to ToothFairy workspace.

Arguments

Name	Required	Description
<file_path>	yes	—

Options

Flag	Required	Default	Description
--import-type	no	Sentinel.UNSET	Import type (optional, auto-detected from extension)
--content-type	no	Sentinel.UNSET	Content type (optional, auto-detected from extension)
--output, -o	no	text	Output format
--verbose, -v	no	False	Show detailed upload information

toothfairy upload <file_path>