# mka1

Command-line interface for the *MK-FGA* API.

[![Built by Speakeasy](https://img.shields.io/badge/Built_by-SPEAKEASY-374151?style=for-the-badge&labelColor=f3f4f6)](https://www.speakeasy.com/?utm_source=github-com/meet-kai/mka1-cli&utm_campaign=cli)
[![License: MIT](https://img.shields.io/badge/LICENSE_//_MIT-3b5bdb?style=for-the-badge&labelColor=eff6ff)](https://opensource.org/licenses/MIT)


<br /><br />
> [!IMPORTANT]
> This CLI is not yet ready for production use. To complete setup please follow the steps outlined in your [workspace](https://app.speakeasy.com/org/meetkai/mk1). Delete this section before > publishing to a package manager.

<!-- Start Summary [summary] -->
## Summary

MK-FGA API: Fine-Grained Authorization API for LLM resources. Caller identity is derived from a validated exchange JWT and propagated by the gateway.
<!-- End Summary [summary] -->

<!-- Start Table of Contents [toc] -->
## Table of Contents
<!-- $toc-max-depth=2 -->
* [mka1](#mka1)
  * [CLI Installation](#cli-installation)
  * [Shell Completion](#shell-completion)
  * [CLI Example Usage](#cli-example-usage)
  * [Authentication](#authentication)
  * [Available Commands](#available-commands)
  * [Request Body Input](#request-body-input)
  * [Server Selection](#server-selection)
  * [Output Formats](#output-formats)
  * [Server-Sent Event Streaming](#server-sent-event-streaming)
  * [Error Handling](#error-handling)
  * [Diagnostics](#diagnostics)
* [Development](#development)
  * [Maturity](#maturity)
  * [Contributions](#contributions)

<!-- End Table of Contents [toc] -->

<!-- Start CLI Installation [installation] -->
## CLI Installation

### Quick Install (Linux/macOS)

```bash
curl -fsSL https://raw.githubusercontent.com/MeetKai/mka1-cli/main/scripts/install.sh | bash
```

### Quick Install (Windows PowerShell)

```powershell
iwr -useb https://raw.githubusercontent.com/MeetKai/mka1-cli/main/scripts/install.ps1 | iex
```

### Go Install

Alternatively, install directly via Go:

```bash
go install github.com/MeetKai/mka1-cli/cmd/mka1@latest
```

### Manual Download

Download pre-built binaries for your platform from the [releases page](https://github.com/MeetKai/mka1-cli/releases).
<!-- End CLI Installation [installation] -->

<!-- Start Shell Completion [completion] -->
## Shell Completion

Shell completions are available for Bash, Zsh, Fish, and PowerShell.

### Bash

```bash
# Add to ~/.bashrc:
source <(mka1 completion bash)

# Or install permanently:
mka1 completion bash > /etc/bash_completion.d/mka1
```

### Zsh

```zsh
# Add to ~/.zshrc:
source <(mka1 completion zsh)

# Or install permanently:
mka1 completion zsh > "${fpath[1]}/_mka1"
```

### Fish

```fish
mka1 completion fish | source

# Or install permanently:
mka1 completion fish > ~/.config/fish/completions/mka1.fish
```

### PowerShell

```powershell
mka1 completion powershell | Out-String | Invoke-Expression
```
<!-- End Shell Completion [completion] -->

<!-- Start CLI Example Usage [usage] -->
## CLI Example Usage

### Example

```bash
mka1 permissions llm grant --bearer-auth 'Bearer test_token' --resource-type completion --resource-id my-completion-123 --user-id user-abc456 --role writer

```
<!-- End CLI Example Usage [usage] -->

<!-- Start Authentication [security] -->
## Authentication

Authentication credentials can be configured in four ways (in order of priority):

### 1. Command-line flags

Pass credentials directly as flags to any command:

```bash
mka1 --bearer-auth <value> <command> [arguments]
```

### 2. Environment variables

Set credentials via environment variables:

| Variable | Description |
|----------|-------------|
| `MKA1_BEARER_AUTH` | Gateway auth: send `Authorization: Bearer <mka1-api-key>`. For multi-user server-side integrations, you can also send `X-On-Behalf-Of: <external-user-id>`. |

### 3. OS Keychain (recommended for workstations)

Credentials are stored securely in your operating system's keychain when you run:

```bash
mka1 configure
```

Secret credentials (tokens, API keys, passwords) are automatically stored in:
- **macOS**: Keychain
- **Linux**: GNOME Keyring / KWallet (via D-Bus Secret Service)
- **Windows**: Windows Credential Locker

If no keychain is available (e.g., in CI environments), credentials fall back to the config file.

### 4. Configuration file

Run the interactive `configure` command to store non-secret settings:

```bash
mka1 configure
```

Configuration is stored in `~/.config/mka1/config.yaml`.
<!-- End Authentication [security] -->

<!-- Start Available Commands [operations] -->
## Available Commands

<details open>
<summary>Available commands</summary>

### [permissions](docs/mka1_permissions.md)

### [permissions-llm](docs/mka1_permissions_permissions-llm.md)

* [`grant`](docs/mka1_permissions_permissions-llm_grant.md) - Grant permission to a user or make public
* [`revoke`](docs/mka1_permissions_permissions-llm_revoke.md) - Revoke permission from a user or remove public access
* [`check`](docs/mka1_permissions_permissions-llm_check.md) - Check user permission

### [llm](docs/mka1_llm.md)

### [batches](docs/mka1_llm_batches.md)

* [`create`](docs/mka1_llm_batches_create.md) - Create a batch
* [`list`](docs/mka1_llm_batches_list.md) - List batches
* [`get`](docs/mka1_llm_batches_get.md) - Get a batch
* [`cancel`](docs/mka1_llm_batches_cancel.md) - Cancel a batch

### [chat](docs/mka1_llm_chat.md)

* [`~~create-chat~~`](docs/mka1_llm_chat_create-chat.md) - [Deprecated] Chat completions for OpenAI SDK/client usage :warning: **Deprecated**
* [`~~stream~~`](docs/mka1_llm_chat_stream.md) - [Deprecated] Streaming chat completions for generated SDK usage :warning: **Deprecated**

### [conversations](docs/mka1_llm_conversations.md)

* [`create`](docs/mka1_llm_conversations_create.md) - Create a conversation
* [`list`](docs/mka1_llm_conversations_list.md) - List conversations
* [`get`](docs/mka1_llm_conversations_get.md) - Retrieve a conversation
* [`update`](docs/mka1_llm_conversations_update.md) - Update a conversation
* [`delete`](docs/mka1_llm_conversations_delete.md) - Delete a conversation
* [`list-items`](docs/mka1_llm_conversations_list-items.md) - List conversation items
* [`create-items`](docs/mka1_llm_conversations_create-items.md) - Create conversation items
* [`delete-items`](docs/mka1_llm_conversations_delete-items.md) - Delete multiple conversation items
* [`get-item`](docs/mka1_llm_conversations_get-item.md) - Retrieve a conversation item
* [`delete-item`](docs/mka1_llm_conversations_delete-item.md) - Delete a conversation item

### [embeddings](docs/mka1_llm_embeddings.md)

* [`list-models`](docs/mka1_llm_embeddings_list-models.md) - List available embedding models
* [`embed`](docs/mka1_llm_embeddings_embed.md) - Create text embeddings

### [feedback](docs/mka1_llm_feedback.md)

* [`create-completion-feedback`](docs/mka1_llm_feedback_create-completion-feedback.md) - Submit feedback for chat completion
* [`get-completion-feedback`](docs/mka1_llm_feedback_get-completion-feedback.md) - Retrieve feedback by completion ID
* [`update-completion-feedback`](docs/mka1_llm_feedback_update-completion-feedback.md) - Update existing completion feedback
* [`batch-get-completion-feedback`](docs/mka1_llm_feedback_batch-get-completion-feedback.md) - Batch retrieve feedback for multiple completions
* [`create-response-feedback`](docs/mka1_llm_feedback_create-response-feedback.md) - Submit feedback for response
* [`get-response-feedback`](docs/mka1_llm_feedback_get-response-feedback.md) - Retrieve feedback by response ID
* [`update-response-feedback`](docs/mka1_llm_feedback_update-response-feedback.md) - Update existing response feedback
* [`batch-get-response-feedback`](docs/mka1_llm_feedback_batch-get-response-feedback.md) - Batch retrieve feedback for multiple responses
* [`start-export`](docs/mka1_llm_feedback_start-export.md) - Start feedback export
* [`get-export-status`](docs/mka1_llm_feedback_get-export-status.md) - Get feedback export status

### [files](docs/mka1_llm_files.md)

* [`upload`](docs/mka1_llm_files_upload.md) - Upload file
* [`list`](docs/mka1_llm_files_list.md) - List files
* [`get`](docs/mka1_llm_files_get.md) - Retrieve file
* [`delete`](docs/mka1_llm_files_delete.md) - Delete file
* [`content`](docs/mka1_llm_files_content.md) - Retrieve file content

### [fine-tuning](docs/mka1_llm_fine-tuning.md)

* [`create`](docs/mka1_llm_fine-tuning_create.md) - Create a fine-tuning job
* [`list`](docs/mka1_llm_fine-tuning_list.md) - List fine-tuning jobs
* [`retrieve`](docs/mka1_llm_fine-tuning_retrieve.md) - Retrieve a fine-tuning job
* [`cancel`](docs/mka1_llm_fine-tuning_cancel.md) - Cancel a fine-tuning job
* [`pause`](docs/mka1_llm_fine-tuning_pause.md) - Pause a fine-tuning job
* [`resume`](docs/mka1_llm_fine-tuning_resume.md) - Resume a fine-tuning job
* [`list-events`](docs/mka1_llm_fine-tuning_list-events.md) - List fine-tuning events
* [`list-checkpoints`](docs/mka1_llm_fine-tuning_list-checkpoints.md) - List fine-tuning checkpoints

### [images](docs/mka1_llm_images.md)

* [`create`](docs/mka1_llm_images_create.md) - Generate images from text descriptions

### [models](docs/mka1_llm_models.md)

* [`list`](docs/mka1_llm_models_list.md) - List available models
* [`get`](docs/mka1_llm_models_get.md) - Retrieve a model
* [`add-registry-model`](docs/mka1_llm_models_add-registry-model.md) - Add a model to the registry
* [`list-registry-models`](docs/mka1_llm_models_list-registry-models.md) - List all registry models
* [`update-registry-model`](docs/mka1_llm_models_update-registry-model.md) - Update a database model in the registry
* [`remove-registry-model`](docs/mka1_llm_models_remove-registry-model.md) - Remove a database model from the registry
* [`get-registry-model`](docs/mka1_llm_models_get-registry-model.md) - Get a specific registry model
* [`check-registry-model-health`](docs/mka1_llm_models_check-registry-model-health.md) - Check health of a specific model

### [prompts](docs/mka1_llm_prompts.md)

* [`create`](docs/mka1_llm_prompts_create.md) - Create a prompt
* [`list`](docs/mka1_llm_prompts_list.md) - List prompts
* [`get`](docs/mka1_llm_prompts_get.md) - Get a prompt
* [`update`](docs/mka1_llm_prompts_update.md) - Update a prompt
* [`delete`](docs/mka1_llm_prompts_delete.md) - Delete a prompt
* [`create-version`](docs/mka1_llm_prompts_create-version.md) - Create a new version
* [`list-versions`](docs/mka1_llm_prompts_list-versions.md) - List versions
* [`get-version`](docs/mka1_llm_prompts_get-version.md) - Get a specific version
* [`rollback`](docs/mka1_llm_prompts_rollback.md) - Rollback to a version

### [responses](docs/mka1_llm_responses.md)

* [`create`](docs/mka1_llm_responses_create.md) - Create an agent-powered response with tool support
* [`list`](docs/mka1_llm_responses_list.md) - List all responses with pagination
* [`get`](docs/mka1_llm_responses_get.md) - Retrieve response by ID with status and results
* [`update`](docs/mka1_llm_responses_update.md) - Update a response
* [`delete`](docs/mka1_llm_responses_delete.md) - Permanently delete a response and its data
* [`cancel`](docs/mka1_llm_responses_cancel.md) - Cancel an in-progress background response
* [`list-input-items`](docs/mka1_llm_responses_list-input-items.md) - List paginated input items for a response
* [`compact`](docs/mka1_llm_responses_compact.md) - Compact a conversation

### [speech](docs/mka1_llm_speech.md)

* [`transcribe`](docs/mka1_llm_speech_transcribe.md) - Speech to text transcription
* [`speak`](docs/mka1_llm_speech_speak.md) - Text to speech
* [`speak-streaming`](docs/mka1_llm_speech_speak-streaming.md) - Streaming text to speech
* [`livekit-token`](docs/mka1_llm_speech_livekit-token.md) - Generate LiveKit room token

### [usage-stats](docs/mka1_llm_usage-stats.md)

* [`completions`](docs/mka1_llm_usage-stats_completions.md) - Get completions usage
* [`responses`](docs/mka1_llm_usage-stats_responses.md) - Get responses usage
* [`conversations`](docs/mka1_llm_usage-stats_conversations.md) - Get conversations usage
* [`embeddings`](docs/mka1_llm_usage-stats_embeddings.md) - Get embeddings usage
* [`extract`](docs/mka1_llm_usage-stats_extract.md) - Get extract usage
* [`classify`](docs/mka1_llm_usage-stats_classify.md) - Get classify usage
* [`vector-stores`](docs/mka1_llm_usage-stats_vector-stores.md) - Get vector stores usage

### [classify](docs/mka1_llm_classify.md)

* [`classify`](docs/mka1_llm_classify_classify.md) - Classify text into predefined categories

### [extract](docs/mka1_llm_extract.md)

* [`extract`](docs/mka1_llm_extract_extract.md) - Extract structured data with inline JSON Schema
* [`create-schema`](docs/mka1_llm_extract_create-schema.md) - Create reusable extraction schema template
* [`get-schema`](docs/mka1_llm_extract_get-schema.md) - Get extraction schema by ID
* [`update-schema`](docs/mka1_llm_extract_update-schema.md) - Update extraction schema by ID
* [`delete-schema`](docs/mka1_llm_extract_delete-schema.md) - Delete extraction schema by ID
* [`extract-with-schema`](docs/mka1_llm_extract_extract-with-schema.md) - Extract data using saved schema template

### [skills](docs/mka1_llm_skills.md)

* [`create`](docs/mka1_llm_skills_create.md) - Create skill
* [`list`](docs/mka1_llm_skills_list.md) - List skills
* [`get`](docs/mka1_llm_skills_get.md) - Retrieve skill
* [`update`](docs/mka1_llm_skills_update.md) - Update skill
* [`delete`](docs/mka1_llm_skills_delete.md) - Delete skill
* [`content`](docs/mka1_llm_skills_content.md) - Download skill content
* [`create-version`](docs/mka1_llm_skills_create-version.md) - Create skill version
* [`list-versions`](docs/mka1_llm_skills_list-versions.md) - List skill versions
* [`get-version`](docs/mka1_llm_skills_get-version.md) - Retrieve skill version
* [`delete-version`](docs/mka1_llm_skills_delete-version.md) - Delete skill version
* [`version-content`](docs/mka1_llm_skills_version-content.md) - Download skill version content
* [`list-preconfigured`](docs/mka1_llm_skills_list-preconfigured.md) - List preconfigured skills

### [vector-stores](docs/mka1_llm_vector-stores.md)

* [`create`](docs/mka1_llm_vector-stores_create.md) - Create a vector store
* [`list`](docs/mka1_llm_vector-stores_list.md) - List vector stores
* [`get`](docs/mka1_llm_vector-stores_get.md) - Retrieve a vector store
* [`update`](docs/mka1_llm_vector-stores_update.md) - Modify a vector store
* [`delete`](docs/mka1_llm_vector-stores_delete.md) - Delete a vector store
* [`search`](docs/mka1_llm_vector-stores_search.md) - Search a vector store
* [`create-file`](docs/mka1_llm_vector-stores_create-file.md) - Add a file to a vector store
* [`list-files`](docs/mka1_llm_vector-stores_list-files.md) - List files in a vector store
* [`get-file`](docs/mka1_llm_vector-stores_get-file.md) - Retrieve a vector store file
* [`update-file`](docs/mka1_llm_vector-stores_update-file.md) - Update file attributes
* [`delete-file`](docs/mka1_llm_vector-stores_delete-file.md) - Remove file from vector store
* [`get-file-content`](docs/mka1_llm_vector-stores_get-file-content.md) - Retrieve parsed file content
* [`create-file-batch`](docs/mka1_llm_vector-stores_create-file-batch.md) - Batch add multiple files to vector store
* [`get-file-batch`](docs/mka1_llm_vector-stores_get-file-batch.md) - Retrieve file batch status
* [`cancel-file-batch`](docs/mka1_llm_vector-stores_cancel-file-batch.md) - Cancel batch file processing
* [`list-files-in-batch`](docs/mka1_llm_vector-stores_list-files-in-batch.md) - List files in a batch

### [guardrails](docs/mka1_guardrails.md)

* [`get`](docs/mka1_guardrails_get.md) - Get guardrails settings
* [`update`](docs/mka1_guardrails_update.md) - Update guardrails settings
* [`test`](docs/mka1_guardrails_test.md) - Test content against guardrails

### [search](docs/mka1_search.md)

### [tables](docs/mka1_search_tables.md)

* [`create`](docs/mka1_search_tables_create.md) - Create Table
* [`get-table-schema`](docs/mka1_search_tables_get-table-schema.md) - Get Table Schema
* [`delete`](docs/mka1_search_tables_delete.md) - Delete Table
* [`insert-data`](docs/mka1_search_tables_insert-data.md) - Insert Data
* [`delete-data`](docs/mka1_search_tables_delete-data.md) - Delete Data
* [`search-data`](docs/mka1_search_tables_search-data.md) - Search
* [`create-indices`](docs/mka1_search_tables_create-indices.md) - Create Indices
* [`list-indices`](docs/mka1_search_tables_list-indices.md) - List Indices
* [`drop-index`](docs/mka1_search_tables_drop-index.md) - Drop Index

### [text-store](docs/mka1_search_text-store.md)

* [`create`](docs/mka1_search_text-store_create.md) - Create Store
* [`add-texts`](docs/mka1_search_text-store_add-texts.md) - Add Texts
* [`delete-texts`](docs/mka1_search_text-store_delete-texts.md) - Delete Texts
* [`search-texts`](docs/mka1_search_text-store_search-texts.md) - Search Texts
* [`delete`](docs/mka1_search_text-store_delete.md) - Delete Store

### [graphrag](docs/mka1_search_graphrag.md)

* [`create-graph-RAG-store`](docs/mka1_search_graphrag_create-graph-RAG-store.md) - Create Store
* [`ingest-graph-RAG-documents`](docs/mka1_search_graphrag_ingest-graph-RAG-documents.md) - Ingest Documents
* [`query-graph-RAG-store`](docs/mka1_search_graphrag_query-graph-RAG-store.md) - Query Store
* [`inspect-graph-RAG-store`](docs/mka1_search_graphrag_inspect-graph-RAG-store.md) - Inspect Graph
* [`delete-graph-RAG-store`](docs/mka1_search_graphrag_delete-graph-RAG-store.md) - Delete Store

### [auth](docs/mka1_auth.md)

### [api-key](docs/mka1_auth_api-key.md)

* [`get-jwt-from-key`](docs/mka1_auth_api-key_get-jwt-from-key.md) - Exchange API key for a JWT token

### [sandbox](docs/mka1_sandbox.md)

* [`create`](docs/mka1_sandbox_create.md) - Create Session
* [`list`](docs/mka1_sandbox_list.md) - List Sessions
* [`get`](docs/mka1_sandbox_get.md) - Get Session
* [`get-url`](docs/mka1_sandbox_get-url.md) - Get Session URL
* [`proxy-browser-port-request`](docs/mka1_sandbox_proxy-browser-port-request.md) - Proxy Browser Port Request
* [`run-command`](docs/mka1_sandbox_run-command.md) - Run Command
* [`run-code`](docs/mka1_sandbox_run-code.md) - Run Code
* [`terminate`](docs/mka1_sandbox_terminate.md) - Terminate Session
* [`get-workspace`](docs/mka1_sandbox_get-workspace.md) - Get Workspace Manifest
* [`download-file`](docs/mka1_sandbox_download-file.md) - Download Workspace File
* [`upload-file`](docs/mka1_sandbox_upload-file.md) - Upload Workspace File

### [schema-5-other](docs/mka1_schema-5-other.md)

* [`get-health`](docs/mka1_schema-5-other_get-health.md) - Health check
* [`get-api-v1-openapi-json`](docs/mka1_schema-5-other_get-api-v1-openapi-json.md) - Legacy OpenAPI document path
* [`get-api-v1-agents-openapi-json`](docs/mka1_schema-5-other_get-api-v1-agents-openapi-json.md) - OpenAPI document

### [agents](docs/mka1_agents.md)

* [`list`](docs/mka1_agents_list.md) - List agents
* [`create`](docs/mka1_agents_create.md) - Create an agent
* [`get`](docs/mka1_agents_get.md) - Retrieve an agent
* [`update`](docs/mka1_agents_update.md) - Update an agent
* [`delete`](docs/mka1_agents_delete.md) - Delete an agent

### [agent-runs](docs/mka1_agent-runs.md)

* [`list`](docs/mka1_agent-runs_list.md) - List runs for an agent
* [`create`](docs/mka1_agent-runs_create.md) - Execute a saved agent
* [`get`](docs/mka1_agent-runs_get.md) - Retrieve an agent run

</details>
<!-- End Available Commands [operations] -->

<!-- Start Request Body Input [stdinpiping] -->
## Request Body Input

Operations that accept a request body support three input methods, with a clear priority chain:

### Individual flags (highest priority)

```bash
mka1 <command> --name "Jane" --age 30
```

### `--body` flag

Provide the entire request body as a JSON string:

```bash
mka1 <command> --body '{"name": "John", "age": 30}'
```

Individual flags override `--body` values:

```bash
# Result: {name: "Jane", age: 30}
mka1 <command> --body '{"name": "John", "age": 30}' --name "Jane"
```

### Stdin piping (lowest priority)

Pipe JSON into any command that accepts a request body:

```bash
echo '{"name": "John", "age": 30}' | mka1 <command>
```

Individual flags override stdin values:

```bash
# Result: {name: "Jane", age: 30}
echo '{"name": "John", "age": 30}' | mka1 <command> --name "Jane"
```

This is useful for chaining commands, reading from files, or scripting:

```bash
# Read body from a file
mka1 <command> < request.json

# Pipe from another command
curl -s https://example.com/data.json | mka1 <command>
```

### Priority

When multiple input methods are used, the priority is:

| Priority | Source | Description |
|----------|--------|-------------|
| 1 (highest) | Individual flags | `--name "Jane"` always wins |
| 2 | `--body` flag | Whole-body JSON via flag |
| 3 (lowest) | Stdin | Piped JSON input |
<!-- End Request Body Input [stdinpiping] -->

<!-- Start Server Selection [server] -->
## Server Selection

### Override Server URL

Use `--server-url` to override the server URL entirely, bypassing any named or indexed server selection:

```bash
mka1 --server-url https://custom-api.example.com <command> [arguments]
```

**Precedence**: `--server-url` > `--server` > default
<!-- End Server Selection [server] -->

<!-- Start Output Formats [output-formats] -->
## Output Formats

Every command supports a `--output-format` flag that controls how the response is rendered to stdout.

### Available formats

| Format | Flag | Description |
|--------|------|-------------|
| Pretty | `--output-format pretty` (default) | Aligned key-value pairs with color, nested indentation. Human-readable at a glance. |
| JSON | `--output-format json` | JSON output. Passthrough when the response is already JSON (preserves original field order and numeric precision). Falls back to typed marshaling otherwise. |
| YAML | `--output-format yaml` | YAML output via standard marshaling. |
| Table | `--output-format table` | Tabular output for array responses. |
| TOON | `--output-format toon` | [Token-Oriented Object Notation](https://github.com/toon-format/spec) — a compact, line-oriented format that typically uses 30–60% fewer tokens than JSON. Well-suited for piping responses into LLM prompts. |

```bash
# Default pretty output
mka1 <command>

# Machine-readable JSON
mka1 <command> --output-format json

# TOON for LLM-friendly compact output
mka1 <command> --output-format toon

# Pipe JSON to jq without using --output-format
mka1 <command> --output-format json | jq '.fieldName'
```

### jq filtering

Use `--jq` to filter or transform the response inline using a [jq](https://jqlang.org) expression. This always outputs JSON and overrides `--output-format`:

```bash
# Extract a single field
mka1 <command> --jq '.name'

# Filter an array
mka1 <command> --jq '.items[] | select(.active == true)'
```

### Color control

Use `--color` to control terminal colors:

| Value | Behavior |
|-------|----------|
| `auto` (default) | Color when stdout is a TTY, plain text otherwise |
| `always` | Always colorize |
| `never` | Never colorize |

The `NO_COLOR` and `FORCE_COLOR` environment variables are also respected.

### Streaming and pagination

When using `--all` (pagination) or streaming operations, output is written incrementally as items arrive:

| Format | Streaming behavior |
|--------|-------------------|
| `json` | One compact JSON object per line ([NDJSON](https://github.com/ndjson/ndjson-spec)) |
| `yaml` | YAML documents separated by `---` |
| `toon` | One TOON-encoded object per block, separated by blank lines |
| `pretty` (default) | Pretty-printed items separated by blank lines |
<!-- End Output Formats [output-formats] -->

<!-- Start Server-Sent Event Streaming [eventstreaming] -->
## Server-Sent Event Streaming

Some operations return server-sent events (SSE). These are streamed to the terminal in real-time, with each event output as a separate JSON object (one per line).

```bash
# Stream events in JSON format
mka1 --output-format json <streaming-command>

# Filter streaming events with jq
mka1 --output-format json <streaming-command> --jq '.data'
```

Events are output as they arrive. Use `Ctrl+C` to stop streaming.
<!-- End Server-Sent Event Streaming [eventstreaming] -->

<!-- Start Error Handling [errors] -->
## Error Handling

The CLI uses standard exit codes to indicate success or failure:

| Exit Code | Meaning |
|-----------|---------|
| `0` | Success |
| `1` | Error (API error, invalid input, etc.) |

On success, the response data is printed to **stdout** as JSON. On failure, error details are printed to **stderr**.

```bash
# Capture output and handle errors
mka1 ... > output.json 2> error.log
if [ $? -ne 0 ]; then
  echo "Error occurred, see error.log"
fi
```
<!-- End Error Handling [errors] -->

<!-- Start Diagnostics [diagnostics] -->
## Diagnostics

The CLI includes two diagnostic flags available on all commands:

### Dry Run

Preview what would be sent without making any network calls:

```bash
mka1 <command> --dry-run
```

Output goes to stderr and includes:
- HTTP method and URL
- Request headers (sensitive values redacted)
- Request body preview (sensitive fields redacted)

The command exits successfully without contacting the API. This is useful for verifying request construction before executing.

### Debug

Log request and response diagnostics while running normally:

```bash
mka1 <command> --debug
```

Debug output goes to stderr and includes:
- Request method, URL, headers, and body preview
- Response status, headers, and body preview
- Transport errors (if any)

The command still executes normally and produces its regular output on stdout.

### Flag Precedence

If both `--dry-run` and `--debug` are set, `--dry-run` takes precedence and no network calls are made.

### Security

Sensitive information is automatically redacted in diagnostic output:
- **Headers**: `Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key`, and other security headers show `[REDACTED]`
- **Body**: JSON fields named `password`, `secret`, `token`, `api_key`, `client_secret`, etc. show `[REDACTED]`

Diagnostic output should still be treated as potentially sensitive operational data.
<!-- End Diagnostics [diagnostics] -->

<!-- Placeholder for Future Speakeasy SDK Sections -->

# Development

## Maturity

This CLI is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage
to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally
looking for the latest version.

## Contributions

While we value open-source contributions to this CLI, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. 
We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release. 

### CLI Created by [Speakeasy](https://www.speakeasy.com/?utm_source=github-com/meet-kai/mka1-cli&utm_campaign=cli)
