---
url: https://docs.mochiexec.io/getting-started/quickstart.md
description: >-
  From a fresh Mochi install to a discovered, running task and its history, in
  the terminal and the desktop app.
---

# Quickstart

This walks through Mochi's core loop on a repo you already have: **find** what you can
run, **run** it, and **remember** what happened.

It assumes you have [installed Mochi](/getting-started/installation).

## 1. Register a workspace

A workspace is a directory Mochi knows about. It is flow's concept, and it works the same
way in both tools:

```sh
cd ~/code/my-project
mochi workspace add my-project . --set
```

flow docs: [Workspaces](https://flowexec.io/guides/workspaces)

What a workspace is, how `flow.yaml` configures it, and how to manage several.

## 2. Find what you can run

Discovery scans the workspace for task files it recognizes: Makefile targets, npm scripts,
Justfile recipes, Taskfile tasks, Compose services, scripts, and more.

```sh
mochi discover --dry-run   # preview what would be found
mochi discover             # surface it
```

Nothing is written into your repo. See [Discovery](/guides/discovery) for the full list of
providers and flags.

## 3. Find it again, from anywhere

Search ranks results by name match, favorites, and how often and how recently you've run
something:

```sh
mochi search build
```

## 4. Run it

Discovered tasks and flow executables run the same way: the verb is the command, followed
by the executable's reference (`workspace/namespace:name`). `mochi search` prints each
result's full reference.

```sh
mochi build my-project/<namespace>:<name>
```

flow docs: [Executables & references](https://flowexec.io/guides/executables)

How verbs, workspaces, namespaces, and names combine into an executable reference.

## 5. See what happened

```sh
mochi logs          # flow's run history
mochi stats         # success rates and busiest tasks, per workspace
```

If a run failed, ask Mochi why:

```sh
mochi ai diagnose <run-id>
```

AI is optional and needs a provider. See [AI](/guides/ai) to set one up, including fully
local models.

## 6. Open the desktop app

```sh
mochi desktop
```

Everything above is also in the app: press `⌘K` to search, open an executable to run it,
and use the Runs page for history.

## Next

* [Discovery](/guides/discovery), in depth
* [The desktop app](/guides/desktop)
* [AI](/guides/ai)