Command Reference

This page summarizes moi-cli command syntax, global options, all 16 core top-level command groups, local file upload flag conventions, and offline introspection tools. For credential setup and role mapping precedence, see Configuration and Authentication.

moi-cli [global options] <command-group> <subcommand> [flags]

Global options

Place global options before <command-group> (single-dash -flag or double-dash --flag syntax is accepted):

Option

Default

Description

-auth <auto|moi|pat>

auto

Authentication mode: auto defaults to Astra sign-in; pass pat explicitly when using a personal access token.

-endpoint <url>

Local fallback (required for remote servers)

Full Product API base URL, such as https://api.moi.matrixorigin.cn/v5 on public cloud.

-api-key <token>

Empty (reads config file)

Raw personal access token for PAT mode, sent in the X-API-Key request header.

-workspace-id <id>

Empty (reads config or login)

Target workspace ID for the current invocation.

-request-timeout <duration>

Command default (30s standard)

Positive HTTP deadline covering request send and response body read, such as 2m or 90s.

-o

false

Writes business responses as JSON to stdout and structured API errors as JSON to stderr.

-no-interactive

false

Disables interactive terminal prompts such as pagination.

-verbose

false

Enables verbose diagnostic output.

-version

false

Prints the binary version and exits (offline).

-help / --help / -h

false

Prints global, group, or subcommand usage and exits (offline).

Top-level command groups

The table below maps all 16 core business command groups to their domain task guides:

Command group

Primary responsibilities

Task guide

config

Manage saved endpoint, PAT, default workspace, and workspace role mappings (set-endpoint, set-api-key, set-workspace, set-role, unset-role, show)

Configuration and Authentication

workspace

List, create, ensure by name (ensure), claim, update, and delete workspaces

Workspaces and Permissions

workspace-member

Inspect current principal, invite and manage workspace members, maintain user tags, and query member audit logs

Workspaces and Permissions

iam

Manage roles, role inheritance, user role bindings, application policies, object grants, and row/column data privileges

Workspaces and Permissions

account

Retrieve workspace database connection parameters and session initialization SQL (db-connection)

Workspaces and Permissions

catalog

Manage catalogs, databases, tables, volumes, file uploads and downloads, data assets, and NL2SQL

Catalogs, Volumes, and Data Sharing

data-share

Check publish names, create and manage cross-workspace data publications, resolve target workspaces, and manage subscriptions

Catalogs, Volumes, and Data Sharing

connector

Manage external connectors, browse database and structured sources, sample Kafka Topic records, and run import/export tasks

Connectors and Data Sync

semantic-model (management)

Manage knowledge bases and semantic entries, upload and append data sources, edit document segments, and reconcile source jobs

Knowledge Bases and Semantic Models

semantic-model (task runtime)

Search bound knowledge bases, paginate evidence, locate parsed Markdown documents, and submit citations under task-scoped authorization

In-Task Knowledge Retrieval

workflow

Deploy workflows, validate candidate projects, trigger executions, configure cron schedules, and publish API/MCP services

Workflows and Services

sql

Execute SQL queries, fetch results and catalog metadata, cancel queries, and manage SQL workbooks and query history

SQL and Dashboards

dashboard

Create and manage dashboards, chart configurations, and workspace task execution overviews

SQL and Dashboards

agent (and conversation)

Invoke agents, submit interactive inputs, manage versions/automations/skill packages, and configure messaging channels and plugins; conversation manages standalone persisted sessions

Agents, Conversations, and Automations, Messaging Channels and Plugins

model / provider-backend

List models, test model connectivity, and manage LLM, Embedding, and Parser provider backends and routing

Models and Provider Backends

compute

Inspect compute specs, create and resize compute instances, pause or resume instances, and read runtime metrics

Compute Instances

In addition to business command groups, moi-cli includes local utility commands: schema and skill inspect wire contracts and bundled operational references offline, and update checks or rolls back managed client installations (see Install and update MOI-CLI).

Local file upload flags

Subcommands that upload local regular files share the --file-path flag convention across domains:

  • Catalogs and volumes: catalog upload, catalog upload-private (plus direct-path aliases catalog upload-file and catalog upload-private-file)

  • Knowledge base sources: semantic-model upload-local-file, semantic-model upload-model-local-file

  • Connector imports: connector local-upload, connector upload (only connector uploads accept repeated --file-path flags for multi-file batches)

  • Agent and skill packages: agent load-agent-package, agent upload-workspace-file, agent inspect-skill-package, agent import-skill-package

Shared upload flags:

Flag

Default

Description

--file-path <path>

Required

Path to a local regular file; mutually exclusive with --json and --json-file on the same subcommand.

--filename <name>

Local file basename

Overrides the filename sent to the server (single-file upload commands).

--max-upload-bytes <bytes>

67108864 (64 MiB)

Maximum total bytes read into memory for a single invocation; increase explicitly when uploading files larger than 64 MiB.

moi-cli -auth pat -o semantic-model upload-local-file \
  --file-path ./handbook.pdf \
  --max-upload-bytes 134217728

Offline introspection: help, JSON schemas, and bundled skills

Before writing complex JSON request files or when working offline, use these three built-in introspection mechanisms to verify exact flags and payload shapes supported by your binary:

1. Command tree and flag help (--help)

moi-cli --help
moi-cli workflow --help
moi-cli workflow deploy --help

2. JSON payload inspection and offline validation (schema)

moi-cli schema prints wire-level JSON input contracts (including nested or string-encoded subfields) and validates local JSON files structurally without sending network requests:

# List all commands with registered offline schemas
moi-cli schema

# Inspect JSON array or nested argument shapes for specific commands
moi-cli schema semantic-model append-sources
moi-cli schema workflow deploy --argument dynamic-service-file
moi-cli schema dashboard create-chart --argument json.chart_config

# Validate a local JSON payload offline (no network call is sent)
moi-cli schema iam create-role --validate-file ./role.json

Use --validate-file on schemas marked as validation-enabled; server-side permission checks, concurrency version checks, and business rules still apply when executing the live command.

3. Bundled capability search and export (skill)

Each moi-cli binary bundles paired operational references that can be searched by keyword, read by relative path, or exported offline to a new directory:

moi-cli skill search --query 'channel create' --limit 5
moi-cli skill read --path references/workflows.md
moi-cli skill export --dir ./moi-cli-skill

skill export --dir requires a non-existent destination directory so existing local files are never overwritten.

Last updated on