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. 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
pnpm easycode helpThe first run installs the dependencies, then prints every command. From the checkout, every command starts with
pnpm easycode.
Run the local app
easycode 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.
pnpm easycode deveasycode startbuilds the app first, then serves it. Pages load faster.easycode runnerruns only the runner, which drives terminals and harness sessions.easycode openregisters 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=1keeps the browser closed and prints the pairing link instead.EASYCODE_PORTandEASYCODE_RUNNER_PORTmove the app and the runner off4738and4739, for example to run beside another copy.EASYCODE_ROOTpoints the app at another workspace.
EASYCODE_PORT=4838 EASYCODE_RUNNER_PORT=4839 pnpm easycode devSign in to your org
The import commands act as you, in your org. Sign in first with easycode login. Set EASYCODE_API_URL to
your EasyCode address:
EASYCODE_API_URL=https://app.easycode.studio pnpm easycode loginYour 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 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.
EASYCODE_API_URL=https://app.easycode.studio pnpm easycode library import ../northwind-kit --org northwind --proposeBring your existing kit covers what it picks up and how to review it.
Knowledge, specs and pages
easycode knowledge importposts a checkout's repo contexts and product maps to your org.easycode specs importimports local spec cycles into a product. Add--dry-runto see what it would do.easycode artifacts importsaves each page folder as one HTML file and publishes it to your org.--dry-runworks 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 importuploads a render catalogue to a release.easycode design noteposts an upgrade note to a release as a draft.
Keep things tidy
easycode 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.
- Connect your harnesses.
- Start a session.
Something wrong or missing? Suggest a change