# The mixel command

> One command for the whole loop. Start an app, check it, test it, open it in Mixel, and publish it.

```sh
uv tool install ox1audio
```

That installs `mixel`, and `uv tool upgrade ox1audio` updates it. `mixel` with nothing after it lists the commands, and `mixel COMMAND --help` explains one. Every flag is in the [command reference](https://docs.0x1audio.com/reference/cli.md).

## The loop

```sh
mixel new "Make It Mono"   # start an app in ./make-it-mono
mixel check                # the rules reviewers apply
mixel test                 # run tests/
mixel run mono --file song.wav --out /tmp/mono
mixel dev                  # open it, and reload it on save
mixel publish              # send this version for review
```

Run `mixel check` after every change. It takes well under a second.

## Reading an error

Every problem has the same shape:

```text
error  permission_undeclared  app.json › permissions.library
       The code uses library (it returns or adds sounds), but app.json doesn't ask for it.
       fix:  add "library": "Save the results to your Library." to permissions (or run mixel check --fix), then say why in your own words
       docs: https://docs.0x1audio.com/app-json#permissions
```

The first line is the code and where it is. Then what happened, in one sentence. The `fix:` line is the change to make; do that first. The `docs:` link explains the rule. Every code is listed, with its usual fix, in [Errors](https://docs.0x1audio.com/errors.md).

`mixel check --fix` makes the fixes it can make safely: it adds a permission the code uses (with a `TODO:` reason for you to write) and a package the code imports. `--strict` also fails on warnings; publishing uses it.

## Running one action

`mixel run ACTION` runs an action the way Mixel would, in the app's own `.venv`:

```sh
mixel run mono --file tests/tone.wav --out /tmp/mono
mixel run convert --file song.wav --set format=flac --json
```

`--file` fills the first `Files` control; `--set NAME=VALUE` sets any other. Bad input gets the same answer the form would give: "Repeats must be a number from 1 to 16. It was 100." What the action makes stays in `--out` for you to listen to. Keep `--out` outside the app's folder, so nothing you try ends up in git.

## For tools and agents

Add `--json` to `check`, `test`, `run`, `doctor`, `publish` and `status` for one JSON object instead of text. Exit codes:

| Code | Means |
| --- | --- |
| `0` | It worked |
| `1` | A check or a test failed |
| `2` | The command line is wrong |
| `3` | You need to sign in |
| `4` | The network or the registry failed |

`mixel docs TOPIC` prints a page of these docs offline, and `mixel docs` follows the links in error messages. For coding agents, [`mixel mcp`](https://docs.0x1audio.com/mcp.md) offers the same loop as tools.

## Is this computer ready?

```sh
mixel doctor
```

It checks Python, uv, git, that Mixel is open with developer mode on, and whether you're signed in, and prints the fix for each thing that's missing.