# The easycode CLI

Run the local app from a source checkout, sign in to your org from a terminal, and import a kit, knowledge or specs.

The `easycode` CLI runs EasyCode from a checkout of its source: the local app and the runner beside it. It also
signs you in to your org from a terminal and imports what you already have, such as a kit or a folder of specs.

Most people don't need it. To run sessions, use the [desktop app](/setup/desktop-app). The CLI is for people who
build on EasyCode itself, and for admins who import content in bulk.

## Install it

You need Node 22.18 or later, pnpm 10 and git. It runs on macOS, Linux, Windows and WSL.

### Get the checkout

Clone the EasyCode source and open its folder in a terminal.

### Run it once

```bash
pnpm easycode help
```

The first run installs the dependencies, then prints every command. From the checkout, every command starts with
`pnpm easycode`.

## Run the local app

[`easycode dev`](/reference/cli#dev) starts the app on `http://127.0.0.1:4738` and the runner on `4739`, then opens your browser on
a one-time pairing link. The local app pairs with that one browser on your machine.

```bash
pnpm easycode dev
```

- [`easycode start`](/reference/cli#start) builds the app first, then serves it. Pages load faster.
- [`easycode runner`](/reference/cli#runner) runs only the runner, which drives terminals and harness sessions.
- [`easycode open`](/reference/cli#open) registers a folder, by default the one you are in, and opens it in the app. The app must
  already be running.

Three environment variables change where it runs:

- `EASYCODE_NO_OPEN=1` keeps the browser closed and prints the pairing link instead.
- `EASYCODE_PORT` and `EASYCODE_RUNNER_PORT` move the app and the runner off `4738` and `4739`, for example to run
  beside another copy.
- `EASYCODE_ROOT` points the app at another workspace.

```bash
EASYCODE_PORT=4838 EASYCODE_RUNNER_PORT=4839 pnpm easycode dev
```

## Sign in to your org

The import commands act as you, in your org. Sign in first with [`easycode login`](/reference/cli#login). Set `EASYCODE_API_URL` to
your EasyCode address:

```bash
EASYCODE_API_URL=https://app.easycode.studio pnpm easycode login
```

Your browser opens on **Sign in a device?**, which names _The easycode command line_. Check that the code matches
the one in your terminal, type its last four characters in the field, then click **Approve**. The CLI keeps your sign-in in a file only your user can read.
When it expires, a command says so: run `login` again.

## Import what you already have

Each import command takes the org's slug with `--org`, and needs `EASYCODE_API_URL` set as above.

### Your kit

[`easycode library import`](/reference/cli#library-import) posts a checkout's skills, agents, guides and MCP servers to your org's library.
Add `--propose` to send them as proposals for review instead of publishing them.

```bash
EASYCODE_API_URL=https://app.easycode.studio pnpm easycode library import ../northwind-kit --org northwind --propose
```

[Bring your existing kit](/guides/bring-your-kit) covers what it picks up and how to review it.

### Knowledge, specs and pages

- [`easycode knowledge import`](/reference/cli#knowledge-import) posts a checkout's repo contexts and product maps to your org.
- [`easycode specs import`](/reference/cli#specs-import) imports local spec cycles into a product. Add `--dry-run` to see what it would do.
- [`easycode artifacts import`](/reference/cli#artifacts-import) saves each page folder as one HTML file and publishes it to your org.
  `--dry-run` works here too.

### Design system releases

> **In the pilot**
>
> The design system is in the pilot. These commands work only when your org has the Design module.

- [`easycode design render import`](/reference/cli#design-render-import) uploads a render catalogue to a release.
- [`easycode design note`](/reference/cli#design-note) posts an upgrade note to a release as a draft.

## Keep things tidy

[`easycode cleanup`](/reference/cli#cleanup) deletes the hidden git refs and isolated worktrees of sessions the runner no longer knows,
in your home folder and every registered folder. It keeps one with unsaved work, or one made in the last ten
minutes. Add `--force` to remove those too.

## Next

- Every command and its arguments: [the CLI reference](/reference/cli).
- [Connect your harnesses](/setup/harnesses).
- [Start a session](/guides/start-a-session).
