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.
Install the CLI
Section titled “Install the CLI”# Install the EcomWeb CLI for your whole computernpm install -g @ecomweb/cli# Check that the CLI is installedecomweb --helpTo run it without installing, use npx, for example npx @ecomweb/cli auth login.
Sign in from your browser
Section titled “Sign in from your browser”- Run
ecomweb auth login. The terminal prints an 8-letter code and opens your browser. - Sign in to the dashboard if the browser asks you to.
- On the Sign in to ecomweb CLI? page, compare the Code with the code in your terminal.
- If the codes match, click Approve.
- When the page says Done, go back to the terminal.
- If you have several stores, choose one from the list.
ecomweb auth login# Or sign in and pick a store at the same timeecomweb 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.
Choose the store
Section titled “Choose the store”Every command works on the selected store. The store ref is the part after /store/ in the dashboard’s address bar.
# See your storesecomweb stores list# Switch to another storeecomweb stores switch <store ref># See the selected storeecomweb stores currentTo run one command on another store without switching, add --store-ref <store ref> to it, or set ECOMWEB_STORE_REF.
Run your first commands
Section titled “Run your first commands”The default output is JSON, which scripts and AI assistants read easily. Add --output table for a table. csv is also available.
ecomweb products list --output tableecomweb orders list --output table# See all command groupsecomweb --help# See the commands and options of one groupecomweb products --helpEvery 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.
Use an API key in CI
Section titled “Use an API key in CI”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.
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.
Check and sign out
Section titled “Check and sign out”# Which account you are signed in withecomweb auth status# Sign out and end this CLI's sessionecomweb auth logoutWhat can the CLI do in my store?
Section titled “What can the CLI do in my store?”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.
Where is my sign-in session stored?
Section titled “Where is my sign-in session stored?”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.