CLI: forge login

npm i -g @forgecommerce/cli

The CLI is generated from the same registry as everything else, so it carries no list of its own: a command that exists in the kernel is callable the day it lands.

1. Log in

forge login --url https://your-instance.example

It asks for an API key and stores it under a name:

logged in to https://your-instance.example as instance "your-instance.example" (key read from environment)
stored in ~/.forge/config.json

Set FORGE_TOKEN and it takes the key from the environment instead of prompting — which is how you would do this in CI.

The key is stored in plain text

~/.forge/config.json holds the URL and the token, unencrypted, like most CLI credential stores. Treat that file as a secret: it is a working credential for your instance, with whatever scopes it carries.

For a shared machine or a CI runner, prefer FORGE_TOKEN in the environment and skip login entirely — every command below works with FORGE_URL + FORGE_TOKEN and touches no config file.

2. See what you are pointed at

forge instances

* your-instance.example  https://your-instance.example  (key stored)

The * is the current one. --instance <name> switches per call; --url <url> talks to a box that was never stored at all.

--instance is a name, --url is a URL

They are not interchangeable, and passing a URL to --instance does not log you in anywhere — it looks for a stored box by that name and does not find one.

3. Read something

forge read whoami --internal

{
  "actor_id": "act_…",
  "tenant_id": "…",
  "scopes": ["catalog.admin.read", "logistics.read", "order.read"]
}

--internal is what picks the operator face of a read. Without it the call goes to the public face, which is a different answer rather than an error:

forge read products --input '{"store": "sto_…", "limit": 1, "projection": "feed"}'

Both writes and reads take --input. There is no --params.

4. Refusals are visible from a script

forge read api_keys --internal

{ "error": { "code": "forbidden", "message": "read requires the admin.users.write scope" } }

echo $?   # 1

A refusal prints the code and exits non-zero, so a shell script notices without parsing JSON. A success exits 0.

5. Write something

forge <command> --input '<json>'

The name is the same one the API, MCP and the SDK use. forge --help prints every command with its scope and summary; each one’s reference page carries the input schema the kernel validates against.

Not every listed command is callable from the CLI today

forge --help prints the whole registry, including the public commands of the shopper journey and the platform commands. Those live on different faces — see surfaces — and calling one from the CLI answers unknown_command.

Operator and integration commands, which is what the CLI is for, work as written.

Useful flags

Flag	What it does
--instance <name>	Which stored box to talk to
--url <url>	Talk to a box that is not stored
--store <id>	Which store a command acts on
--idempotency-key <k>	Make a retry safe
--internal	Ask the operator face of a read

Every one of them also has an environment variable — FORGE_INSTANCE, FORGE_URL, FORGE_TOKEN — and the flag wins over the environment, which wins over ~/.forge.

Next

• MCP: connect an agent — the same registry as tools.
• Operate via CLI — the day-to-day recipes.