Matilda
Contact
Foundations

Install Matilda Code.

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

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

The fastest path on any platform
Install with npm
Shell
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:

Shell
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.

Shell
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.

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.

Shell
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:

Shell
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