Metadata-Version: 2.4
Name: maitai-cli
Version: 0.1.3
Summary: CLI for the Maitai Platform Developer API (api/v1)
Author-email: Maitai <support@trymaitai.com>
License: MIT
Project-URL: Documentation, https://docs.trymaitai.ai
Project-URL: API Reference, https://docs.trymaitai.ai/api-reference
Project-URL: Portal, https://portal.trymaitai.com
Keywords: maitai,cli,api,ai,llm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"

# Maitai CLI

Command-line interface for the [Maitai Platform Developer API](https://docs.trymaitai.ai/api-reference) (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

```bash
# 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](https://portal.trymaitai.com) under **Settings → API Keys**, then:

```bash
# 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):

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

## Usage

```bash
# 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](https://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](https://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": "..."}}`

<!-- GENERATED_ENDPOINTS_START -->
## 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 |

<!-- GENERATED_ENDPOINTS_END -->

