---
name: manta-client
description: |
  CLI client for Manta AI Agent platform. Use manta-client to create and manage AI agent jobs,
  skills, workspaces, secrets, schedules, and assistants. Jobs run in isolated Kubernetes pods.
  Use when: creating agent jobs, managing skills/workspaces/secrets, checking job status/logs,
  scripting agent automation, or any manta-client CLI operations.
allowed-tools: Bash, Read
---

# Manta Client CLI

`manta-client` is the CLI for Manta AI Agent platform. It manages agent jobs that run in isolated K8s pods.

## Global Flags

- `-q, --quiet` — Script/AI-agent mode: minimal output, one ID per line
- `-j, --json` — JSON output
- `-v, --version` — Show version

## Installation & Setup

```bash
# Install
uv tool install manta-client \
  --index-url https://pypi.org/simple/ \
  --extra-index-url https://nexus.zilliz.cc/repository/pypi-internal/simple/

# Upgrade (also syncs local skill)
uv tool install --upgrade manta-client \
  --index-url https://pypi.org/simple/ \
  --extra-index-url https://nexus.zilliz.cc/repository/pypi-internal/simple/
manta-client skill install-local

# Auth
manta-client auth login

# Verify
manta-client doctor
```

## Authentication

| Command | Description |
|---------|-------------|
| `manta-client auth login` | Feishu OAuth2 login (opens browser) |
| `manta-client auth logout` | Clear credentials |
| `manta-client auth whoami` | Show current user |

## Configuration

Config file: `~/.manta/config.toml`

| Command | Description |
|---------|-------------|
| `manta-client config show` | Display current config |
| `manta-client config set <key> <value>` | Set value (`api_url`, `auth_url`) |
| `manta-client config path` | Show config file path |

## Job Management (Core)

Jobs are the core concept — each job is one AI agent execution in an isolated K8s pod.

### Create

```bash
manta-client job create -m "your task"           # Basic
manta-client job create -m "task" -f             # Follow logs
manta-client job create -m "task" -s <skill_id>  # With skill
manta-client job create -m "task" -w <workspace> # With workspace
manta-client job create -m "task" -C <parent_id> # Continue conversation
manta-client job create -m "task" -M opus        # Specify model
manta-client job create -F config.yaml           # From file
```

Options: `-m` (message), `-s` (skill), `-w` (workspace), `-C` (conversation/parent job), `-M` (model: claude-sonnet-4-5/opus/haiku), `-i` (JSON input), `-F` (config file), `-f` (follow), `-T` (timeout), `-j` (json)

### List

```bash
manta-client job list                    # Your recent 20
manta-client job list --all              # All users
manta-client job list --status running   # By status
manta-client job list --search "keyword" # Search title/prompt
manta-client job list --since 2026-03-01 # From date
```

Options: `-l` (limit), `-s` (status), `-a` (all), `-u` (user), `-S` (search), `--since`, `--before`

### Other Job Commands

| Command | Description |
|---------|-------------|
| `manta-client job info <id>` | Job details |
| `manta-client job logs <id> -f` | Stream live logs (SSE) |
| `manta-client job logs <id> -f -T 300` | Follow with timeout |
| `manta-client job wait <id> --timeout 600` | Wait for completion |
| `manta-client job cancel <id>` | Cancel running job |
| `manta-client job retry <id>` | Retry failed/cancelled |
| `manta-client job retry <id> -f` | Retry and follow |
| `manta-client job artifacts <id>` | List output files |
| `manta-client job download <id> <file> -o <path>` | Download artifact |

**Statuses**: `pending` → `running` → `completed` / `failed` / `cancelled`

## Skill Management

Skills inject domain knowledge into agents.

| Command | Description |
|---------|-------------|
| `manta-client skill list` | List available skills |
| `manta-client skill info <slug>` | Skill details |
| `manta-client skill add <owner>/<repo>/<path>[@tag]` | Add from GitHub |
| `manta-client skill update <slug>` | Update to latest |
| `manta-client skill remove <slug>` | Remove skill |
| `manta-client skill sync-all` | Bulk update all |
| `manta-client skill install-local` | Install/update bundled Claude Code skill |

Example: `manta-client skill add zilliztech/manta/agent-skills/milvus-deploy@v1.0.0`

## Workspace Management

Workspaces bind Git repos and K8s clusters. Use `-w` with job create.

| Command | Description |
|---------|-------------|
| `manta-client workspace create -n <name> -c <cluster> -r <repo>` | Create |
| `manta-client workspace list` | List |
| `manta-client workspace info <name>` | Details |
| `manta-client workspace update <name> -r <repo>` | Update |
| `manta-client workspace sync <name>` | Sync repos to PVC |
| `manta-client workspace delete <name>` | Delete |

Repo format: `url[@branch][:/path]`

## Secret Management

Secrets store sensitive values (encrypted, never displayed).

| Command | Description |
|---------|-------------|
| `manta-client secret create -n <name> -v <value>` | Create |
| `echo "val" \| manta-client secret create -n <name> --value-stdin` | From stdin |
| `manta-client secret list` | List (values hidden) |
| `manta-client secret update <id> -v <new>` | Update |
| `manta-client secret delete <id>` | Delete |

Well-known names: `GITHUB_TOKEN`, `GITLAB_TOKEN`, `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`

Priority: user-scoped → global → system config

## Cluster Management (Read-Only)

| Command | Description |
|---------|-------------|
| `manta-client cluster list` | List clusters |
| `manta-client cluster info <name>` | Cluster details |
| `manta-client cluster download-kubeconfig <name>` | Download kubeconfig |

## Schedule Management

| Command | Description |
|---------|-------------|
| `manta-client schedule create -n <name> -a <agent> --cron "expr" -p "prompt"` | Create |
| `manta-client schedule list` | List |
| `manta-client schedule delete <id>` | Delete |

## Assistant Management

| Command | Description |
|---------|-------------|
| `manta-client assistant create -n <name> -p "system prompt"` | Create |
| `manta-client assistant query <id> -m "message"` | Query |
| `manta-client assistant list` | List |
| `manta-client assistant stop <id>` | Stop |

## Agent Information

| Command | Description |
|---------|-------------|
| `manta-client agent list` | List agents |
| `manta-client agent info <name>` | Agent details |

## Diagnostics

| Command | Description |
|---------|-------------|
| `manta-client doctor` | Connectivity diagnostics |
| `manta-client self info` | Client environment info |
| `manta-client self update` | Upgrade instructions |
| `manta-client self clean --all` | Clean local cache |
| `manta-client skill install-local` | Sync bundled skill to Claude Code |

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error |
| 2 | Auth failure (re-login needed) |
| 3 | Not found |
| 4 | Validation error |
| 10 | Job failed |
| 11 | Job cancelled |
| 12 | Timeout |

## Scripting Patterns

### Create → Wait → Get Result (most common)

```bash
JOB_ID=$(manta-client -q job create -m "your task")
manta-client -q job wait "$JOB_ID" --timeout 600
case $? in
  0)  manta-client job info "$JOB_ID" --json ;;
  10) echo "Job failed" >&2; exit 1 ;;
  11) echo "Job cancelled" >&2; exit 1 ;;
  12) echo "Timed out" >&2; exit 1 ;;
esac
```

### Multi-turn Conversation

```bash
JOB1=$(manta-client -q job create -m "Analyze the issue")
manta-client job create -m "Now fix it" -C $JOB1 -f
```

### Set Up Credentials (non-interactive)

```bash
echo "$GITHUB_TOKEN" | manta-client secret create -n "GITHUB_TOKEN" --value-stdin
echo "$API_KEY" | manta-client secret create -n "ANTHROPIC_API_KEY" --value-stdin
```

## Best Practices

1. Use `-q` in scripts — machine-friendly, one ID per line
2. Use `-f` for interactive — follow logs in real-time
3. Use `job wait` for automation — meaningful exit codes
4. Use `-C` for multi-turn — chain jobs with shared context
5. Use workspaces — bind repos + clusters for job environments
6. Use skills — inject domain knowledge for better results
7. Set personal secrets — `GITHUB_TOKEN`, `ANTHROPIC_API_KEY`
8. Run `manta-client skill install-local` after upgrading — keep Claude Code skill in sync
