# Install Matilda Code

> Install the CLI, sign in, and open your first session.

Source: https://maincode.com/docs/installation
Section: Matilda Code · Matilda documentation

---

## Prerequisites

Matilda Code runs anywhere Node runs. Before you install, make sure you have:

- Node.js 22 or newer, on macOS, Linux, or Windows
- A Maincode account
- A terminal open inside a project you want to work in

## Install

**Install with npm** — The fastest path on any platform

```bash
npm install -g @maincode-ai/matilda-code@latest
```

The package installs two binaries, `matilda` and `matilda-code`. They are the
same program.

After a global install, npm prints the exact directory it installed into. That
is not always on your `PATH`, so if the shell cannot find `matilda`, add the
npm prefix and try again:

```bash
export PATH="$(npm prefix -g)/bin:$PATH"
```

## Sign in

Authenticate once per machine. `matilda auth login` opens your browser and
starts a temporary callback listener on `127.0.0.1`. Finish the sign-in there.
If the browser does not open by itself, paste the URL the CLI prints.

```bash
matilda auth login
```

On success the CLI writes a refresh token to `~/.matilda/matilda-auth.json`
with user-only file permissions, and refreshes access tokens for you from then
on.

> **Note** — For interactive use you do not need an API key. Keys are for CI and other
> non-interactive jobs, covered in [Headless and CI](https://maincode.com/docs/headless) — mint one
> in the [dashboard](https://maincode.com/dashboard/keys) or with the `matilda-key` CLI.

## Run it

Change into a project and start Matilda Code from its root. It reads your
working tree in place; it does not copy your code anywhere.

```bash
cd your-project
matilda
```

You land in an interactive session. Describe a change in plain language and
Matilda Code reads the relevant files, plans the edits, and runs commands,
pausing for your approval before anything is written or executed. Type `/help`
to see the commands available inside a session.

## Verify

To confirm the CLI is installed and signed in:

```bash
matilda --version
matilda auth status
```

`auth status` prints your sign-in state; `whoami` is an alias for it. If you
need to sign out of this device, `matilda auth logout` clears the local
credentials. It does not revoke sessions on your other machines.

## Next steps

- Read [Core concepts](https://maincode.com/docs/core-concepts) to see how the model, the agent,
  and the action layer fit together.
- Learn [how an agent run works](https://maincode.com/docs/agent-runs), including the five
  approval modes, before you hand it a large change.
- Run it in CI with [Headless and CI](https://maincode.com/docs/headless).