---
url: https://docs.mochiexec.io/reference/cli.md
description: >-
  The mochi CLI reference. An overview of the commands Mochi adds to the flow
  CLI, with a generated page for every command.
---

# CLI Reference

`mochi` is the flow CLI with Mochi's commands added. Every command, flow's included, has a
page generated from its own help: see [`mochi`](./mochi) and the list in the sidebar. This
page is the overview of what Mochi adds.

The rest (`exec` and every verb, `browse`, `logs`, `workspace`, `vault`, `secret`,
`template`, `cache`, `config`, `mcp`) behaves as in flow. Two differences: `mochi sync` also
refreshes [discovered](/guides/discovery) tasks, and flow's `cli update` isn't available;
update Mochi by running its installer again.

Every command that prints results takes `-o, --output text|json`.

flow docs: [flow CLI reference](https://flowexec.io/cli/)

flow's guides to its commands, which you run as `mochi`.

Every command accepts `-h, --help`, plus the global flags `-L, --log-level` and `--sync`.
Commands marked 🔑 [need a license](/getting-started/license).

## Discovery

| Command | Description |
|---|---|
| [`mochi discover [workspace]`](./mochi_discover) 🔑 | Find the tasks a workspace already defines and make them runnable. `--dry-run`, `--force`, `--only`, `--providers` |
| [`mochi discover status [workspace]`](./mochi_discover_status) 🔑 | What the last scan found, without scanning again |
| [`mochi sync`](./mochi_sync) | Also re-scans the current workspace and every workspace discovered before |

Guide: [Discovery](/guides/discovery)

## AI

| Command | Description |
|---|---|
| [`mochi ai describe <verb> <id>`](./mochi_ai_describe) 🔑 | Suggest a one-line description for an executable |
| [`mochi ai document [workspace]`](./mochi_ai_document) 🔑 | Describe every undescribed executable. `--write`, `--overwrite`, `-n` |
| [`mochi ai explain <verb> <id>`](./mochi_ai_explain) 🔑 | Plain-English explanation of an executable |
| [`mochi ai diagnose <run-id>`](./mochi_ai_diagnose) 🔑 | Likely cause and fixes for a failed run |
| [`mochi ai insights [workspace]`](./mochi_ai_insights) 🔑 | Recommendations from run statistics. `-n` |
| [`mochi ai chat [prompt]`](./mochi_ai_chat) 🔑 | Ask a question with tool access to your workspaces |
| [`mochi ai usage`](./mochi_ai_usage) 🔑 | Mochi gateway usage and credits for your license |
| [`mochi ai usage local`](./mochi_ai_usage_local) 🔑 | Locally recorded usage for your own providers |
| [`mochi ai config view`](./mochi_ai_config_view) 🔑 | Show the current provider configuration |
| [`mochi ai config set provider <name>`](./mochi_ai_config_set_provider) 🔑 | Configure and activate a provider. See [AI Providers](/reference/ai-providers) |
| [`mochi ai config set tools --tier <tier>`](./mochi_ai_config_set_tools) 🔑 | Highest tool tier chat may use: `read-only`, `caution`, `edit`, `full` |
| [`mochi ai config set usage`](./mochi_ai_config_set_usage) 🔑 | Retention for the local usage log |
| [`mochi ai config test`](./mochi_ai_config_test) 🔑 | Check that the configured provider actually works |

Guide: [AI](/guides/ai)

## Search, favorites, and stats

| Command | Description |
|---|---|
| [`mochi search [query]`](./mochi_search) 🔑 | Usage-ranked search across executables and workspaces. `-n` |
| [`mochi favorite add\|remove`](./mochi_favorite) 🔑 | Star or unstar a workspace or executable. `--workspace <name>` or `--executable <ref>` |
| [`mochi favorite list`](./mochi_favorite_list) 🔑 | List favorites |
| [`mochi stats [workspace]`](./mochi_stats) 🔑 | Runs, success rates, and busiest executables. `-n` |

Guide: [Search, Favorites & Stats](/guides/search-and-favorites)

## Views

| Command | Description |
|---|---|
| [`mochi views list`](./mochi_views_list) | List saved views |
| [`mochi views show <view>`](./mochi_views_show) | Render a view |
| [`mochi views refs <view>`](./mochi_views_refs) | Print the executable references a view selects |
| [`mochi views reset`](./mochi_views_reset) | Delete every view, including a views file that can't be read |

Guide: [Views](/guides/views)

## Editing

| Command | Description |
|---|---|
| [`mochi executable edit REF --data <json>`](./mochi_executable_edit) 🔑 | Replace one executable in place, keeping comments and siblings |
| [`mochi executable set-description REF TEXT`](./mochi_executable_set-description) 🔑 | Set or clear one executable's description, including a discovered one |
| [`mochi executable add --file <path> --content <yaml>`](./mochi_executable_add) 🔑 | Append executables to an existing flow file |
| [`mochi workspace edit NAME`](./mochi_workspace_edit) 🔑 | Edit `--description`, `--display-name`, `--tags` in place |

Guide: [Editing Executables](/guides/editing)

## Vault presets

| Command | Description |
|---|---|
| [`mochi vault preset list`](./mochi_vault_preset_list) 🔑 | Available presets |
| [`mochi vault preset preflight --preset <p>`](./mochi_vault_preset_preflight) 🔑 | Check the provider is installed and usable |
| [`mochi vault preset connect --preset <p>`](./mochi_vault_preset_connect) 🔑 | Run the provider's sign-in step |
| [`mochi vault preset browse --preset <p>`](./mochi_vault_preset_browse) 🔑 | List what a provider holds |
| [`mochi vault preset render NAME --preset <p>`](./mochi_vault_preset_render) 🔑 | Render a vault configuration file. `--out`, `--set key=value` |

Guide: [Vault Presets](/guides/vault-presets)

## Desktop

| Command | Description |
|---|---|
| [`mochi desktop`](./mochi_desktop) 🔑 | Launch the desktop app (`MOCHI_DESKTOP_PATH` overrides the location) |
| [`mochi desktop open <target>`](./mochi_desktop_open) 🔑 | Open a `mochi://` link or executable reference in the app |

Guide: [Desktop App](/guides/desktop)

## License

| Command | Description |
|---|---|
| [`mochi license set`](./mochi_license_set) | Validate and register a license key, entered at a masked prompt, read with `--file`, or piped on stdin |
| [`mochi license trial`](./mochi_license_trial) | Start a 7-day trial. `--email` |
| [`mochi license status`](./mochi_license_status) | License state, plan, and key dates on this machine |

Guide: [Licensing](/getting-started/license)

## Telemetry

| Command | Description |
|---|---|
| [`mochi telemetry status`](./mochi_telemetry_status) | Whether anonymous usage reporting is on, and the install ID |
| [`mochi telemetry enable`](./mochi_telemetry_enable) | Turn usage reporting on |
| [`mochi telemetry disable`](./mochi_telemetry_disable) | Turn it off and delete the install ID |

Reference: [Telemetry](/reference/telemetry)

## Trust

| Command | Description |
|---|---|
| [`mochi trust list`](./mochi_trust_list) | Every workspace's trust state and rules |
| [`mochi trust set <workspace> trusted\|restricted`](./mochi_trust_set) | Trust or restrict a workspace |
| [`mochi trust reset <workspace>`](./mochi_trust_reset) | Forget a workspace's trust and rules |
| [`mochi trust check <verb> <id>`](./mochi_trust_check) | Whether a task can run without asking |
| [`mochi trust rule add <workspace> allow\|ask <pattern>`](./mochi_trust_rule_add) | Allow or ask for matching tasks |
| [`mochi trust rule remove <workspace> <pattern>`](./mochi_trust_rule_remove) | Remove a rule |

Guide: [Workspace Trust](/guides/workspace-trust)