# The emo CLI

> The emo commands: init, connect, login, check, token, dashboard refresh, mcp, doctor and run, with exit codes, skills and how emo fits into CI.

`emo` is the command line for the Emolysis engine. It is built for terminals, scripts and CI, and it runs the same commands as the desktop app and the MCP server.

## Commands

| Command                                 | What it does                                                                 |
| --------------------------------------- | ---------------------------------------------------------------------------- |
| `emo init <name>`                       | Create a pipeline project: `models/`, `pipelines/`, `tests/`, `emolysis.yml` |
| `emo connect <platform>`                | Connect a platform, for example `emo connect databricks`                     |
| `emo login`, `emo logout`, `emo whoami` | Sign in, sign out, show who is signed in                                     |
| `emo check`                             | Lint, golden tests and a cost estimate for the project, for CI               |
| `emo token create`, `list`, `revoke`    | Manage your organization's machine tokens for CI                             |
| `emo dashboard refresh`                 | Refresh a dashboard's data; `--publish` publishes it                         |
| `emo mcp`                               | Start the MCP server over standard input and output                          |
| `emo doctor`                            | Check your setup; exits with an error when a required check fails            |
| `emo version`                           | Print the engine version                                                     |
| `emo commands`                          | List every command id, with `--schemas` for their parameters                 |
| `emo run <id> --params '<json>'`        | Run any command by its id with JSON parameters                               |

Deploying is `emo run pipeline.deploy`.

Run `emo login` to sign in. Every command except `emo version`, `emo doctor`, `emo commands` and the sign-in commands needs an Emolysis account, local files included. A command you run while signed out starts the sign-in flow: `emo` prints a short code, and you confirm it in the browser, where you sign in with your GitHub, Microsoft or Google account. The code expires after 15 minutes.

## A session

```sh
emo init orders
emo connect databricks
emo check
```

Each line maps to a step in [How Emolysis works](https://emolysis.com/docs/how-it-works). The [Quickstart](https://emolysis.com/docs/quickstart) walks through the same session in the app.

## Commands by id

Every action in Emolysis is a command with an id of the form `<area>.<verb>`, such as `query.run`, `dialect.transpile`, `dialect.lint`, `template.list`, `template.render`, `template.test` or `dashboard.publish`. `emo commands` lists them all. `emo run` calls any of them:

```sh
emo run dialect.transpile --params '{"sql": "select 1", "write": "databricks"}'
```

`emo run` prints the result as JSON and exits with status 0, or prints an error object and exits with status 1. The error object carries one of nine error codes; see [Error codes](https://emolysis.com/docs/error-codes). That makes `emo run` the dependable way to use Emolysis from scripts and CI.

The short commands, such as `emo version` and `emo doctor`, are shortcuts to registered commands and add no logic of their own. A command available on one surface is available on all of them: the app, the CLI and the [MCP server](https://emolysis.com/docs/mcp-server).

## Exit codes

| Result                               | Exit status |
| ------------------------------------ | ----------- |
| A command returned a result          | 0           |
| A command returned an error object   | 1           |
| `emo doctor`, a required check fails | 1           |

In scripts, use the status and read the error's code, not its message, to decide what to do. The messages are for people.

## Skills in the app and in coding agents

The same engine offers a few higher-level requests as skills, with slot schemas so the agent asks only for what is missing:

| Skill                                         | What it does                                                                               |
| --------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `/dashboard "<question>"`                     | Find sources, propose a semantic model, build the gold table, chart it, publish on request |
| `/pipeline <shape> from <source> to <target>` | Fill the template for a shape, run its tests, deploy on request                            |
| `/connect`                                    | Connect a platform                                                                         |
| `/migrate <table> to <platform>` (planned)    | Translate a pipeline to another platform and re-run its tests                              |
| `/explain <pipeline>`                         | Describe a pipeline's lineage and cost in plain language                                   |

## CI

In CI, use `emo run` for anything scripted and the [GitHub checks](https://emolysis.com/docs/github-checks) for pull requests. Because the commands are the same everywhere, the steps you run on your machine are the steps a runner runs.

## Installing

`emo` comes with the desktop app. A package on PyPI is planned; see [Installation](https://emolysis.com/docs/installation). The name `emolysis` is reserved on PyPI with an empty placeholder.

## Status

The command names, the options and the output formats can change before the first release. The command id form, the two exit statuses of `emo run` and the nine error codes are fixed.

---

Page: https://emolysis.com/docs/cli. Emolysis is a product of Bandpey GmbH, Munich, Germany. It is in private development, and nothing is released yet.