maitai-cli 0.1.1

CLI for the Maitai Platform Developer API (api/v1)

Maitai CLI

Command-line interface for the Maitai Platform Developer API (api/v1).

Resource commands (applications, agents, etc.) are generated from the OpenAPI spec. When the API changes, run python scripts/generate_openapi.py from the repo root to regenerate the CLI.

Install

# From the maitai-mono repo (cli directory)
pip install .

# Or install in development mode
pip install -e .

Authenticate

Create an API key in the Portal under Settings → API Keys, then:

# Interactive: saves key to ~/.maitai/config
maitai login --api-key YOUR_MAITAI_API_KEY

# Or use environment variable (no login needed)
export MAITAI_API_KEY="YOUR_MAITAI_API_KEY"

For a custom base URL (e.g. local dev):

maitai login --api-key YOUR_KEY --base-url http://localhost:5000/api/v1

Usage

# Check auth status
maitai whoami

# List resources
maitai applications --list
maitai agents --list
maitai intent-groups --list
maitai sessions --list
maitai sentinels --list
maitai datasets --list
maitai test-sets --list
maitai test-runs --list
maitai models --list
maitai models --available
maitai evaluations --list
maitai finetune-runs --list
maitai conversation-trees --list

# Get by ID
maitai applications --get 42
maitai agents --get 1
maitai intent-groups --get 5

# Create application
maitai applications --create "My App:my-app"

# Delete application
maitai applications --delete 42

# Raw API calls (any endpoint)
maitai api GET /applications
maitai api GET /applications/42
maitai api POST /applications -b '{"application_name":"Test","application_ref_name":"test"}'
maitai api PUT /applications/42 -b '{"application_name":"Updated"}'
maitai api DELETE /applications/42

API Reference

The CLI wraps the Maitai Developer API. Full documentation:

• External docs: docs.trymaitai.ai
• OpenAPI spec: docs/external/openapi.yaml in this repo
• Internal docs: docs/internal/ in this repo

Authentication

All requests use the X-Maitai-Api-Key header. Create keys at portal.trymaitai.com → Settings → API Keys.

Base URL

• Production: https://api.trymaitai.ai/api/v1
• Override with MAITAI_BASE_URL or maitai login --base-url

Response Format

• Success: {"data": {...}}
• Paginated: {"data": [...], "pagination": {"total": N, "offset": 0, "limit": 25}}
• Error: {"error": {"status": 401, "message": "..."}}

Supported API endpoints

The CLI wraps all api/v1 endpoints. Use maitai api METHOD path for any endpoint:

Method	Path	Operation
GET	/agents	listAgents
POST	/agents	createAgent
DELETE	/agents/actions/{action_id}	deleteAgentAction
GET	/agents/actions/{action_id}	getAgentAction
PUT	/agents/actions/{action_id}	updateAgentAction
PUT	/agents/actions/{action_id}/disable	disableAction
PUT	/agents/actions/{action_id}/enable	enableAction
POST	/agents/actions/{action_id}/publish	publishActionVersion
GET	/agents/actions/{action_id}/versions	listActionVersions
GET	/agents/tasks/{task_id}/tree	getAgentTaskTree
DELETE	/agents/{agent_id}	deleteAgent
GET	/agents/{agent_id}	getAgent
PUT	/agents/{agent_id}	updateAgent
GET	/agents/{agent_id}/actions	listAgentActions
POST	/agents/{agent_id}/actions	createAgentAction
DELETE	/agents/{agent_id}/form-fields	deleteFormFields
GET	/agents/{agent_id}/form-fields	getFormFields
PUT	/agents/{agent_id}/form-fields	updateFormFields
POST	/agents/{agent_id}/publish	publishAgentVersion
GET	/agents/{agent_id}/releases	listAgentReleases
DELETE	/agents/{agent_id}/releases/{name}	deleteAgentRelease
PUT	/agents/{agent_id}/releases/{name}	upsertAgentRelease
GET	/agents/{agent_id}/routing/config	getRoutingConfig
PUT	/agents/{agent_id}/routing/config	updateRoutingConfig
POST	/agents/{agent_id}/routing/rules	createRoutingRule
DELETE	/agents/{agent_id}/routing/rules/{rule_id}	deleteRoutingRule
PUT	/agents/{agent_id}/routing/rules/{rule_id}	updateRoutingRule
GET	/agents/{agent_id}/sessions	listAgentSessions
GET	/agents/{agent_id}/sessions/{session_id}	getAgentSessionDetail
GET	/agents/{agent_id}/sessions/{session_id}/timeline	getAgentSessionTimeline
GET	/agents/{agent_id}/subagents	listSubAgents
POST	/agents/{agent_id}/subagents	addSubAgent
DELETE	/agents/{agent_id}/subagents/{child_agent_id}	removeSubAgent
PUT	/agents/{agent_id}/subagents/{child_agent_id}/disable	disableSubAgent
PUT	/agents/{agent_id}/subagents/{child_agent_id}/enable	enableSubAgent
GET	/agents/{agent_id}/tasks/{task_id}/timeline	getAgentTaskTimeline
GET	/agents/{agent_id}/versions	listAgentVersions
GET	/agents/{agent_id}/versions/{version}	getAgentVersion
GET	/applications	listApplications
POST	/applications	createApplication
DELETE	/applications/{application_id}	deleteApplication
GET	/applications/{application_id}	getApplication
PUT	/applications/{application_id}	updateApplication
GET	/applications/{application_id}/config	getApplicationConfig
PUT	/applications/{application_id}/config	updateApplicationConfig
GET	/applications/{application_id}/intents	listApplicationIntents
GET	/applications/{application_id}/intents/{intent_id}	getApplicationIntent
GET	/applications/{application_id}/intents/{intent_id}/config	getIntentConfig
PUT	/applications/{application_id}/intents/{intent_id}/config	updateIntentConfig
GET	/applications/{application_id}/models	listApplicationModels
GET	/applications/{application_id}/sessions	listApplicationSessions
GET	/applications/{application_id}/workflow-runs	listApplicationWorkflowRuns
GET	/conversation-trees	listConversationTrees
DELETE	/conversation-trees/{tree_id}	deleteConversationTree
GET	/conversation-trees/{tree_id}	getConversationTree
GET	/conversation-trees/{tree_id}/status	getConversationTreeStatus
GET	/conversation-trees/{tree_id}/versions	listConversationTreeVersions
GET	/datasets	listDatasets
POST	/datasets	createDataset
DELETE	/datasets/{dataset_id}	deleteDataset
GET	/datasets/{dataset_id}	getDataset
PUT	/datasets/{dataset_id}	updateDataset
DELETE	/datasets/{dataset_id}/requests	removeRequestsFromDataset
GET	/datasets/{dataset_id}/requests	listDatasetRequests
POST	/datasets/{dataset_id}/requests	addRequestsToDataset
GET	/evaluations	listEvaluations
POST	/evaluations	createEvaluation
GET	/evaluations/{evaluation_run_id}	getEvaluation
GET	/evaluations/{evaluation_run_id}/results	getEvaluationResults
GET	/finetune-runs	listFinetuneRuns
POST	/finetune-runs	createFinetuneRun
GET	/finetune-runs/{run_id}	getFinetuneRun
POST	/finetune-runs/{run_id}/cancel	cancelFinetuneRun
GET	/finetune-runs/{run_id}/metrics	getFinetuneRunMetrics
GET	/intent-groups	listIntentGroups
GET	/intent-groups/{intent_group_id}	getIntentGroup
GET	/intent-groups/{intent_group_id}/compositions	listIntentGroupCompositions
GET	/intent-groups/{intent_group_id}/config	getIntentGroupConfig
PUT	/intent-groups/{intent_group_id}/config	updateIntentGroupConfig
GET	/intent-groups/{intent_group_id}/datasets	listIntentGroupDatasets
GET	/intent-groups/{intent_group_id}/intents	listIntentsByGroup
GET	/intent-groups/{intent_group_id}/models	listIntentGroupModels
GET	/intent-groups/{intent_group_id}/requests	listIntentGroupRequests
GET	/intent-groups/{intent_group_id}/sentinels	listIntentGroupSentinels
GET	/intent-groups/{intent_group_id}/test-sets	listIntentGroupTestSets
GET	/models	listModels
GET	/models/available	listAvailableModels
POST	/models/{model_id}/disable	disableModel
POST	/models/{model_id}/enable	enableModel
GET	/requests	listRequests
GET	/requests/{request_id}	getRequest
PUT	/requests/{request_id}/response	updateRequestResponse
GET	/sentinels	listSentinels
POST	/sentinels	createSentinel
DELETE	/sentinels/{sentinel_id}	deleteSentinel
GET	/sentinels/{sentinel_id}	getSentinel
PUT	/sentinels/{sentinel_id}	updateSentinel
GET	/sessions	listSessions
GET	/sessions/{session_id}	getSession
POST	/sessions/{session_id}/feedback	setSessionFeedback
GET	/sessions/{session_id}/timeline	getSessionTimeline
GET	/test-runs	listTestRuns
POST	/test-runs	createTestRun
DELETE	/test-runs/{test_run_id}	deleteTestRun
GET	/test-runs/{test_run_id}	getTestRun
GET	/test-runs/{test_run_id}/progress	getTestRunProgress
GET	/test-runs/{test_run_id}/requests	listTestRunRequests
GET	/test-sets	listTestSets
POST	/test-sets	createTestSet
DELETE	/test-sets/{test_set_id}	deleteTestSet
GET	/test-sets/{test_set_id}	getTestSet
PUT	/test-sets/{test_set_id}	updateTestSet
DELETE	/test-sets/{test_set_id}/requests	removeRequestsFromTestSet
GET	/test-sets/{test_set_id}/requests	listTestSetRequests
POST	/test-sets/{test_set_id}/requests	addRequestsToTestSet