Skip to content

Install and sign in to the EcomWeb CLI

The EcomWeb CLI is a command-line tool for working with a store: listing products, updating orders, managing custom data and getting theme code. AI assistants such as Claude Code and Codex also use it to work on a store.

You sign in by approving in your browser, with no API key. The CLI uses your own role in each store. This guide needs Node.js 24 or later.

Terminal window
# Install the EcomWeb CLI for your whole computer
npm install -g @ecomweb/cli
# Check that the CLI is installed
ecomweb --help

To run it without installing, use npx, for example npx @ecomweb/cli auth login.

  1. Run ecomweb auth login. The terminal prints an 8-letter code and opens your browser.
  2. Sign in to the dashboard if the browser asks you to.
  3. On the Sign in to ecomweb CLI? page, compare the Code with the code in your terminal.
  4. If the codes match, click Approve.
  5. When the page says Done, go back to the terminal.
  6. If you have several stores, choose one from the list.
Terminal window
ecomweb auth login
# Or sign in and pick a store at the same time
ecomweb auth login --store-ref <store ref>

The approval page also shows the Device asking to sign in and the address the request came from. If you did not just run the sign-in command, click Deny.

If the browser does not open, open the link the terminal printed, or run ecomweb auth login --no-browser. If the page shows an Enter your sign-in code box, enter the code and click Continue. A code can be used once and expires after 10 minutes. When the page says This code is no longer valid, run the sign-in command again.

Every command works on the selected store. The store ref is the part after /store/ in the dashboard’s address bar.

Terminal window
# See your stores
ecomweb stores list
# Switch to another store
ecomweb stores switch <store ref>
# See the selected store
ecomweb stores current

To run one command on another store without switching, add --store-ref <store ref> to it, or set ECOMWEB_STORE_REF.

The default output is JSON, which scripts and AI assistants read easily. Add --output table for a table. csv is also available.

Terminal window
ecomweb products list --output table
ecomweb orders list --output table
# See all command groups
ecomweb --help
# See the commands and options of one group
ecomweb products --help

Every command accepts --dry-run. Commands that change data use it to preview without changing anything, so check the result of a dry run before you rely on it.

On a server or in CI no one can approve a sign-in, so use a secret key. Put it in the ECOMWEB_API_KEY variable (or pass --api-key). The key takes priority over a signed-in session.

Terminal window
ECOMWEB_API_KEY=<secret key> ecomweb products list --store-ref <store ref>

Create the key with only the scopes the job needs. See Create and manage API keys and the scopes guide.

Terminal window
# Which account you are signed in with
ecomweb auth status
# Sign out and end this CLI's session
ecomweb auth logout

What your role in that store allows. For example, if you are staff, the CLI cannot change settings that staff cannot change in the dashboard.

The code on the page does not match the code in my terminal?

Section titled “The code on the page does not match the code in my terminal?”

Click Deny. Someone else may be trying to sign in with your account. Then run ecomweb auth login again if you need to.

In your operating system’s credential store when there is one, for example Keychain on macOS. Otherwise the CLI saves it as a file under ~/.config/ecomweb/credentials/, readable only by your account. API keys are never written to disk.