@ezship/cli

The ez command and the contract: every operation on an ezship Instance or Site, run identically by the CLI and the Studio. Apache-2.0; requires Node 20 or later. ez help is the guide to building a Site.

Signing in

ez login acme discovers https://acme.ezship.dev and signs in with a code emailed to you (`--email

Each login is a saved connection in ~/.ez/connections.json. ez login bravo saves another one while Acme stays primary; ez logins lists them, ez switch bravo changes the primary, and --instance acme targets one command. A bound folder always means its own Instance. For local development use ez login http://dev.localhost:5199; no system DNS change is needed.

ez account [--password] opens the platform's account page. ez tokens and ez token revoke <id> list and revoke tokens (--json supported). ez logout [--all] forgets saved credentials; it does not revoke a token.

The Instance folder

ez clone [<instance>] pulls every Site you may open into sites/<folder>/, named for the Site, and the Global Workspace into global/; ez pull --all refreshes them, following each folder's binding, never its name, and moves a folder when its Site is renamed. No Site may be named global or sites.

ez global <command> works on the Global Working Copy from a Site's folder. Admins and Builders add Tables, nullable columns and indexes to global/db/schema.sql; every schema edit regenerates global/db/types.d.ts, and Site code imports row types from global/db/types. Run ez global check, then ez global push, before a Preview or Deploy can create what you added: a push makes published definitions permanent and runs no DDL, and a deployed Site keeps its code and Declaration until it is deployed again. Limited Builders read, check and preview their own copy.

ez preview and ez dev build with the global/ beside the Site (or --global-dir <dir>, which must be pulled for the same Instance and Builder), else with the pushed Global files; a Preview of a retained Version uses the pushed ones. ez dev watches both copies and uploads after every change; the Preview reloads itself after each successful build. ez check runs the hosted Pipeline's full checks.

Editor setup

Clone, Pull and ez dev write editor setup for VS Code and other TypeScript editors: one root tsconfig.json extending .ez/editor/tsconfig.json, shared by global/ and every Site folder, with the React, JSX, @ezship/react and Global declarations and the database row types. No npm install is needed in a Working Copy. A standalone Working Copy, a Site with its own tsconfig.json, or one using a different --global-dir keeps its own setup; a custom configuration can extend ./.ez/editor/tsconfig.json. Editor metadata never enters status, Push or Preview, and the declarations follow the installed CLI release.

What is in the package

• ez.mjs: the terminal binding: login, the primary, Site selection, Working Copies on disk.
• connections.mjs: discovery, saved identities, the primary, target and request binding, the contract number.
• commands.mjs (@ezship/cli/contract): every command against the Workspace interface, and ROUTES, how each remote method reaches the API (httpWorkspace for clients, matchRoute for the platform).
• schema.mjs (@ezship/cli/schema): the App Database rule table, the db/schema.sql parser and the schema planner.
• types.d.mts (@ezship/cli/types): the HTTP API's shapes.
• account.mjs: ez tokens and ez token revoke; editor.mjs: the editor setup; bindings.mjs: where a folder's binding lives.
• local-fetch.mjs: HTTP for *.localhost, keeping the Instance origin while connecting to loopback.
• update-check.mjs: at most once a day, whether npm has a newer release; ez then says so on standard error after the command. EZ_NO_UPDATE_CHECK=1 or CI turns it off.

Plain JavaScript, zero runtime dependencies, no build. Tests: bun run test.