# Mochi

> Mochi is the desktop app and CLI built on flow: it finds the tasks already in your repos, runs them from one place, remembers every run, and explains them with AI.

Mochi is built on flow, the open-source workflow engine. Every `flow` command is also a `mochi` command, and flow files, workspaces, and vaults work unchanged.

This documentation covers only what Mochi adds. For flow's concepts (workspaces, executables, vaults, templates, the flow file schema, and the MCP server), read https://flowexec.io/llms.txt.

## Table of Contents

### Introduction

- [What is Mochi?](https://docs.mochiexec.io/introduction/what-is-mochi.md): Mochi is a desktop app and CLI built on the open-source flow engine. Every flow command works in Mochi; Mochi adds discovery, a desktop app, AI, and cross-workspace history on top.

### Getting Started

- [Installation](https://docs.mochiexec.io/getting-started/installation.md): Mochi is in early access. Join the list to get the installer for the Mochi CLI and desktop app on macOS, Linux, or Windows.
- [Quickstart](https://docs.mochiexec.io/getting-started/quickstart.md): From a fresh Mochi install to a discovered, running task and its history, in the terminal and the desktop app.
- [Licensing](https://docs.mochiexec.io/getting-started/license.md): How to activate a Mochi license, check its status, and which commands it covers. Commands that come from flow never need one.

### Guides

- [Discovery](https://docs.mochiexec.io/guides/discovery.md): Mochi finds the Makefile targets, npm scripts, Justfile recipes, Taskfile tasks, Compose services and scripts already in a repo, and makes them runnable and searchable without writing anything into it.
- [Desktop App](https://docs.mochiexec.io/guides/desktop.md): A tour of the Mochi desktop app on macOS, Linux, and Windows (experimental), covering the command palette, workbench tabs, runs, chats, vaults, the system tray, and deep links.
- [AI](https://docs.mochiexec.io/guides/ai.md): Use AI in Mochi to describe, explain, and diagnose executables, get insights from run history, and chat with tool access to your workspaces, using your own key, a local model, or Mochi's gateway.
- [Search, Favorites & Stats](https://docs.mochiexec.io/guides/search-and-favorites.md): Find any executable across every workspace with usage-ranked search, star the ones you use most, and see run statistics per workspace.
- [Views](https://docs.mochiexec.io/guides/views.md): Views are saved, cross-workspace dashboards built from sections, such as executable queries, run history, workspace status, and notes.
- [Editing Executables](https://docs.mochiexec.io/guides/editing.md): Add and edit executables and workspace settings from the Mochi CLI or desktop app, without losing the comments and formatting in your flow files.
- [Vault Presets](https://docs.mochiexec.io/guides/vault-presets.md): Tested configurations that connect flow vaults to 1Password, pass, and AWS SSM Parameter Store, read-only.
- [Agents & MCP](https://docs.mochiexec.io/guides/agents-and-mcp.md): Connect coding agents to your workflows with the MCP server, chat with Mochi's own agent, and see what agents ran.
- [Workspace Trust](https://docs.mochiexec.io/guides/workspace-trust.md): Decide which workspaces Mochi runs tasks from without asking, refine it per task with rules, and control what agents connected over MCP may run.

### Reference

- [CLI Reference](https://docs.mochiexec.io/reference/cli.md): The mochi CLI reference. An overview of the commands Mochi adds to the flow CLI, with a generated page for every command.
- [AI Providers](https://docs.mochiexec.io/reference/ai-providers.md): Every AI provider Mochi supports, including the Mochi gateway, OpenAI, Anthropic, Gemini, Ollama, and custom endpoints, and the options to configure each.
- [Keyboard Shortcuts](https://docs.mochiexec.io/reference/keyboard-shortcuts.md): Default keyboard shortcuts in the Mochi desktop app. Every one can be rebound in Settings.
- [Telemetry](https://docs.mochiexec.io/reference/telemetry.md): What Mochi's opt-in usage reporting sends, what it never sends, and how to turn it off.
- [flow Reference](https://docs.mochiexec.io/reference/flow.md): Where to find flow's reference documentation, including flow file, workspace, and config schemas, the CLI, and JSON schemas. All of it applies to Mochi unchanged.

#### CLI Reference

- [CLI Reference](https://docs.mochiexec.io/reference/cli.md): The mochi CLI reference. An overview of the commands Mochi adds to the flow CLI, with a generated page for every command.
- [mochi](https://docs.mochiexec.io/reference/cli/mochi.md): Run and organize your development tasks
- [mochi ai](https://docs.mochiexec.io/reference/cli/mochi_ai.md): Describe, explain, and diagnose executables with AI
- [mochi browse](https://docs.mochiexec.io/reference/cli/mochi_browse.md): Discover and explore available executables.
- [mochi cache](https://docs.mochiexec.io/reference/cli/mochi_cache.md): Manage temporary key-value data.
- [mochi config](https://docs.mochiexec.io/reference/cli/mochi_config.md): View and update global flow configuration.
- [mochi desktop](https://docs.mochiexec.io/reference/cli/mochi_desktop.md): Open the Mochi desktop app
- [mochi discover](https://docs.mochiexec.io/reference/cli/mochi_discover.md): Find the tasks already in a workspace and make them runnable
- [mochi exec](https://docs.mochiexec.io/reference/cli/mochi_exec.md): Execute any executable by reference.
- [mochi executable](https://docs.mochiexec.io/reference/cli/mochi_executable.md): Manage executables
- [mochi favorite](https://docs.mochiexec.io/reference/cli/mochi_favorite.md): Star workspaces and executables
- [mochi license](https://docs.mochiexec.io/reference/cli/mochi_license.md): Manage your Mochi license
- [mochi logs](https://docs.mochiexec.io/reference/cli/mochi_logs.md): View execution history and logs.
- [mochi mcp](https://docs.mochiexec.io/reference/cli/mochi_mcp.md): Start Model Context Provider (MCP) server for AI assistant integration
- [mochi schema](https://docs.mochiexec.io/reference/cli/mochi_schema.md): Validate flowfiles and workspace configs against their schemas.
- [mochi search](https://docs.mochiexec.io/reference/cli/mochi_search.md): Search executables and workspaces
- [mochi secret](https://docs.mochiexec.io/reference/cli/mochi_secret.md): Manage secrets stored in a vault.
- [mochi stats](https://docs.mochiexec.io/reference/cli/mochi_stats.md): Show run statistics across workspaces and executables
- [mochi sync](https://docs.mochiexec.io/reference/cli/mochi_sync.md): Refresh workspace cache and discover new executables.
- [mochi telemetry](https://docs.mochiexec.io/reference/cli/mochi_telemetry.md): Manage anonymous usage reporting
- [mochi template](https://docs.mochiexec.io/reference/cli/mochi_template.md): Manage flowfile templates.
- [mochi trust](https://docs.mochiexec.io/reference/cli/mochi_trust.md): Manage which workspaces can run tasks without asking
- [mochi vault](https://docs.mochiexec.io/reference/cli/mochi_vault.md): Manage sensitive secret stores.
- [mochi views](https://docs.mochiexec.io/reference/cli/mochi_views.md): Manage saved views
- [mochi workspace](https://docs.mochiexec.io/reference/cli/mochi_workspace.md): Manage development workspaces.

##### mochi ai

- [mochi ai chat](https://docs.mochiexec.io/reference/cli/mochi_ai_chat.md): Ask AI about your workspaces, executables, and runs
- [mochi ai config](https://docs.mochiexec.io/reference/cli/mochi_ai_config.md): Choose and configure your AI provider
- [mochi ai describe](https://docs.mochiexec.io/reference/cli/mochi_ai_describe.md): Suggest a one-line description for an executable
- [mochi ai diagnose](https://docs.mochiexec.io/reference/cli/mochi_ai_diagnose.md): Diagnose a failed run and suggest fixes
- [mochi ai document](https://docs.mochiexec.io/reference/cli/mochi_ai_document.md): Generate descriptions for a workspace's undescribed executables
- [mochi ai explain](https://docs.mochiexec.io/reference/cli/mochi_ai_explain.md): Explain in plain English what an executable does
- [mochi ai insights](https://docs.mochiexec.io/reference/cli/mochi_ai_insights.md): Recommend what to fix, from run history
- [mochi ai usage](https://docs.mochiexec.io/reference/cli/mochi_ai_usage.md): Show your Mochi gateway usage and credits

###### mochi ai config

- [mochi ai config set](https://docs.mochiexec.io/reference/cli/mochi_ai_config_set.md): Change AI settings
- [mochi ai config test](https://docs.mochiexec.io/reference/cli/mochi_ai_config_test.md): Check that an AI provider works
- [mochi ai config view](https://docs.mochiexec.io/reference/cli/mochi_ai_config_view.md): Show the current AI provider configuration

####### mochi ai config set

- [mochi ai config set provider](https://docs.mochiexec.io/reference/cli/mochi_ai_config_set_provider.md): Set up an AI provider and make it the active one
- [mochi ai config set tools](https://docs.mochiexec.io/reference/cli/mochi_ai_config_set_tools.md): Set what AI chat is allowed to do
- [mochi ai config set usage](https://docs.mochiexec.io/reference/cli/mochi_ai_config_set_usage.md): Set how long local AI usage is kept

###### mochi ai usage

- [mochi ai usage local](https://docs.mochiexec.io/reference/cli/mochi_ai_usage_local.md): Show AI usage recorded on this machine

##### mochi cache

- [mochi cache clear](https://docs.mochiexec.io/reference/cli/mochi_cache_clear.md): Clear cache data. Use --all to remove data across all scopes.
- [mochi cache get](https://docs.mochiexec.io/reference/cli/mochi_cache_get.md): Get cached data by key.
- [mochi cache list](https://docs.mochiexec.io/reference/cli/mochi_cache_list.md): List all keys in the store.
- [mochi cache remove](https://docs.mochiexec.io/reference/cli/mochi_cache_remove.md): Remove a key from the cached data store.
- [mochi cache set](https://docs.mochiexec.io/reference/cli/mochi_cache_set.md): Set cached data by key.

##### mochi config

- [mochi config add](https://docs.mochiexec.io/reference/cli/mochi_config_add.md): Add an entry to a global configuration list.
- [mochi config get](https://docs.mochiexec.io/reference/cli/mochi_config_get.md): Get the current global configuration values.
- [mochi config remove](https://docs.mochiexec.io/reference/cli/mochi_config_remove.md): Remove an entry from a global configuration list.
- [mochi config reset](https://docs.mochiexec.io/reference/cli/mochi_config_reset.md): Restore the default flow configuration values. This will overwrite the current configuration.
- [mochi config set](https://docs.mochiexec.io/reference/cli/mochi_config_set.md): Set a global configuration value.

###### mochi config add

- [mochi config add verb](https://docs.mochiexec.io/reference/cli/mochi_config_add_verb.md): Register custom executable verbs.

###### mochi config remove

- [mochi config remove verb](https://docs.mochiexec.io/reference/cli/mochi_config_remove_verb.md): Unregister custom executable verbs.

###### mochi config set

- [mochi config set log-mode](https://docs.mochiexec.io/reference/cli/mochi_config_set_log-mode.md): Set the default log mode.
- [mochi config set namespace](https://docs.mochiexec.io/reference/cli/mochi_config_set_namespace.md): Change the current namespace.
- [mochi config set notifications](https://docs.mochiexec.io/reference/cli/mochi_config_set_notifications.md): Enable or disable notifications.
- [mochi config set theme](https://docs.mochiexec.io/reference/cli/mochi_config_set_theme.md): Set the theme for the TUI views
- [mochi config set timeout](https://docs.mochiexec.io/reference/cli/mochi_config_set_timeout.md): Set the default timeout for executables.
- [mochi config set tui](https://docs.mochiexec.io/reference/cli/mochi_config_set_tui.md): Enable or disable the interactive terminal UI experience.
- [mochi config set update-check](https://docs.mochiexec.io/reference/cli/mochi_config_set_update-check.md): Enable or disable background CLI update checks.
- [mochi config set workspace-mode](https://docs.mochiexec.io/reference/cli/mochi_config_set_workspace-mode.md): Switch between fixed and dynamic workspace modes.

##### mochi desktop

- [mochi desktop open](https://docs.mochiexec.io/reference/cli/mochi_desktop_open.md): Open an executable or mochi:// link in the desktop app

##### mochi discover

- [mochi discover status](https://docs.mochiexec.io/reference/cli/mochi_discover_status.md): Show what the last scan found, without scanning again

##### mochi executable

- [mochi executable add](https://docs.mochiexec.io/reference/cli/mochi_executable_add.md): Append executables to an existing flow file
- [mochi executable edit](https://docs.mochiexec.io/reference/cli/mochi_executable_edit.md): Replace one executable's definition in its flow file
- [mochi executable set-description](https://docs.mochiexec.io/reference/cli/mochi_executable_set-description.md): Set one executable's description

##### mochi favorite

- [mochi favorite add](https://docs.mochiexec.io/reference/cli/mochi_favorite_add.md): Star a workspace or executable
- [mochi favorite list](https://docs.mochiexec.io/reference/cli/mochi_favorite_list.md): List favorited workspaces and executables
- [mochi favorite remove](https://docs.mochiexec.io/reference/cli/mochi_favorite_remove.md): Unstar a workspace or executable

##### mochi license

- [mochi license set](https://docs.mochiexec.io/reference/cli/mochi_license_set.md): Register a license key on this machine
- [mochi license status](https://docs.mochiexec.io/reference/cli/mochi_license_status.md): Show this machine's license
- [mochi license trial](https://docs.mochiexec.io/reference/cli/mochi_license_trial.md): Start a free 7-day trial

##### mochi logs

- [mochi logs attach](https://docs.mochiexec.io/reference/cli/mochi_logs_attach.md): Stream log output from a running background process by run ID.
- [mochi logs clear](https://docs.mochiexec.io/reference/cli/mochi_logs_clear.md): Clear execution history and logs.
- [mochi logs kill](https://docs.mochiexec.io/reference/cli/mochi_logs_kill.md): Terminate a running background process by run ID.

##### mochi schema

- [mochi schema validate](https://docs.mochiexec.io/reference/cli/mochi_schema_validate.md): Validate flow files and workspace configs against their schemas.

##### mochi secret

- [mochi secret get](https://docs.mochiexec.io/reference/cli/mochi_secret_get.md): Get the value of a secret in the current vault.
- [mochi secret link](https://docs.mochiexec.io/reference/cli/mochi_secret_link.md): Link a name in the current vault to a secret in an external provider.
- [mochi secret list](https://docs.mochiexec.io/reference/cli/mochi_secret_list.md): List secrets stored in the current vault.
- [mochi secret remove](https://docs.mochiexec.io/reference/cli/mochi_secret_remove.md): Remove a secret from the vault.
- [mochi secret set](https://docs.mochiexec.io/reference/cli/mochi_secret_set.md): Set a secret in the current vault. If no value is provided, you will be prompted to enter one.
- [mochi secret unlink](https://docs.mochiexec.io/reference/cli/mochi_secret_unlink.md): Remove a link from the current vault, leaving the secret itself untouched.

##### mochi telemetry

- [mochi telemetry disable](https://docs.mochiexec.io/reference/cli/mochi_telemetry_disable.md): Turn anonymous usage reporting off and delete the install ID
- [mochi telemetry enable](https://docs.mochiexec.io/reference/cli/mochi_telemetry_enable.md): Turn anonymous usage reporting on
- [mochi telemetry status](https://docs.mochiexec.io/reference/cli/mochi_telemetry_status.md): Show whether usage reporting is on

##### mochi template

- [mochi template add](https://docs.mochiexec.io/reference/cli/mochi_template_add.md): Register a flowfile template by name.
- [mochi template generate](https://docs.mochiexec.io/reference/cli/mochi_template_generate.md): Generate workspace executables and scaffolding from a flowfile template.
- [mochi template get](https://docs.mochiexec.io/reference/cli/mochi_template_get.md): Get a flowfile template's details. Either it's registered name or file path can be used.
- [mochi template list](https://docs.mochiexec.io/reference/cli/mochi_template_list.md): List registered and workspace-discovered flowfile templates.
- [mochi template remove](https://docs.mochiexec.io/reference/cli/mochi_template_remove.md): Unregister a flowfile template by name.

##### mochi trust

- [mochi trust check](https://docs.mochiexec.io/reference/cli/mochi_trust_check.md): Report whether an executable can run without asking
- [mochi trust list](https://docs.mochiexec.io/reference/cli/mochi_trust_list.md): List every workspace's trust
- [mochi trust reset](https://docs.mochiexec.io/reference/cli/mochi_trust_reset.md): Forget a workspace's trust and rules, so you are asked again
- [mochi trust rule](https://docs.mochiexec.io/reference/cli/mochi_trust_rule.md): Allow or ask for specific tasks within a workspace
- [mochi trust set](https://docs.mochiexec.io/reference/cli/mochi_trust_set.md): Trust or restrict a workspace

###### mochi trust rule

- [mochi trust rule add](https://docs.mochiexec.io/reference/cli/mochi_trust_rule_add.md): Add a rule, replacing any rule with the same pattern
- [mochi trust rule remove](https://docs.mochiexec.io/reference/cli/mochi_trust_rule_remove.md): Remove the rule with a pattern

##### mochi vault

- [mochi vault create](https://docs.mochiexec.io/reference/cli/mochi_vault_create.md): Create a new vault.
- [mochi vault edit](https://docs.mochiexec.io/reference/cli/mochi_vault_edit.md): Edit the configuration of an existing vault.
- [mochi vault get](https://docs.mochiexec.io/reference/cli/mochi_vault_get.md): Get the details of a vault.
- [mochi vault list](https://docs.mochiexec.io/reference/cli/mochi_vault_list.md): List all available vaults.
- [mochi vault preset](https://docs.mochiexec.io/reference/cli/mochi_vault_preset.md): Connect a vault to 1Password, pass, or AWS SSM
- [mochi vault remove](https://docs.mochiexec.io/reference/cli/mochi_vault_remove.md): Remove an existing vault.
- [mochi vault switch](https://docs.mochiexec.io/reference/cli/mochi_vault_switch.md): Switch the active vault.

###### mochi vault preset

- [mochi vault preset browse](https://docs.mochiexec.io/reference/cli/mochi_vault_preset_browse.md): List what a provider holds, to choose secrets to link
- [mochi vault preset connect](https://docs.mochiexec.io/reference/cli/mochi_vault_preset_connect.md): Sign in to a provider
- [mochi vault preset list](https://docs.mochiexec.io/reference/cli/mochi_vault_preset_list.md): List the available vault presets
- [mochi vault preset preflight](https://docs.mochiexec.io/reference/cli/mochi_vault_preset_preflight.md): Check that a provider is installed and signed in
- [mochi vault preset render](https://docs.mochiexec.io/reference/cli/mochi_vault_preset_render.md): Write a vault configuration from a preset

##### mochi views

- [mochi views list](https://docs.mochiexec.io/reference/cli/mochi_views_list.md): List saved views
- [mochi views refs](https://docs.mochiexec.io/reference/cli/mochi_views_refs.md): Print the executable references a view selects, one per line
- [mochi views reset](https://docs.mochiexec.io/reference/cli/mochi_views_reset.md): Delete every view
- [mochi views show](https://docs.mochiexec.io/reference/cli/mochi_views_show.md): Render a view by name or ID

##### mochi workspace

- [mochi workspace add](https://docs.mochiexec.io/reference/cli/mochi_workspace_add.md): Initialize a new workspace from a local path or Git URL.
- [mochi workspace edit](https://docs.mochiexec.io/reference/cli/mochi_workspace_edit.md): Edit a workspace's display name, description, or tags
- [mochi workspace get](https://docs.mochiexec.io/reference/cli/mochi_workspace_get.md): Get workspace details. If the name is omitted, the current workspace is used.
- [mochi workspace list](https://docs.mochiexec.io/reference/cli/mochi_workspace_list.md): List all registered workspaces.
- [mochi workspace remove](https://docs.mochiexec.io/reference/cli/mochi_workspace_remove.md): Remove an existing workspace.
- [mochi workspace switch](https://docs.mochiexec.io/reference/cli/mochi_workspace_switch.md): Switch the current workspace.
- [mochi workspace update](https://docs.mochiexec.io/reference/cli/mochi_workspace_update.md): Pull latest changes for a git-sourced workspace.