# CLI

The orbcart command. Local development, keys, tax rates and access to the Explorer.

The CLI ships with `@orbcart/runtime`. Run it from your commerce Worker's directory:

```sh
pnpm exec orbcart <command>
```

| Command                | What it does                                                 |
| ---------------------- | ------------------------------------------------------------ |
| `orbcart dev`          | Runs your Worker locally and writes keys for the storefront. |
| `orbcart keys issue`   | Issues keys for a deployed `test` environment.               |
| `orbcart tax sync`     | Imports today's EU VAT rates.                                |
| `orbcart tax status`   | Shows the state of the EU VAT import.                        |
| `orbcart access setup` | Puts Cloudflare Access in front of the Explorer.             |
| `orbcart members add`  | Gives a person a role in an environment.                     |

## orbcart dev

```sh
pnpm exec orbcart dev --channel de --channel ch --keys ../storefront/.dev.vars
```

Starts your Worker with `wrangler dev` on port 8787 and writes into the `--keys` file:

```dotenv
ORBCART_URL=http://localhost:8787
ORBCART_PUBLISHABLE_KEY=pk_test_...      # the first channel
ORBCART_PUBLISHABLE_KEY_CH=pk_test_...   # every further channel, by name
ORBCART_SECRET_KEY=sk_test_...
```

Keys the environment still knows are kept, so restarting changes nothing. Any
other option goes to `wrangler dev` unchanged, such as `--port 8788` or
`--env-file ../../.dev.vars`.

## orbcart keys issue

```sh
pnpm exec orbcart keys issue --env test --channel de --url https://shop-commerce-test.example.workers.dev
```

Writes `ORBCART_URL`, a publishable key and the secret key to
`.orbcart/keys/test-de.env` with owner-only permissions. Options:

| Option            | Default                            |
| ----------------- | ---------------------------------- |
| `--keys <file>`   | `.orbcart/keys/test-<channel>.env` |
| `--worker <name>` | `<wrangler name>-test`             |
| `--config <file>` | `wrangler.jsonc`                   |

Only `test` is allowed for now. Wrangler must be logged into the same Cloudflare
account. The file contains a secret key: never commit or paste it.

## orbcart tax

```sh
pnpm exec orbcart tax sync --env test
pnpm exec orbcart tax status --env test
```

`sync` runs the daily EU import now, within its normal schedule and retries. It
exits with an error unless today's rates are available. `status` prints the
state and always exits 0. [Tax →](/integrations/tax#read-tax-status)

## orbcart access setup

```sh
export CLOUDFLARE_API_TOKEN=...   # needs Access permissions
pnpm exec orbcart access setup --env test --host commerce.example.com --allow @example.com
```

Protects the order Explorer at `https://<host>/explorer` with Cloudflare Access:
one-time PINs by email for the listed addresses or domains. Running it again
updates the same application. `wrangler login` grants no Access permissions, so
an API token is needed.

## orbcart members add

```sh
pnpm exec orbcart members add anna@example.com --role support --env test
```

| Role        | Sees buyers' personal data | Can refund |
| ----------- | :------------------------: | :--------: |
| `owner`     |              ✓             |      ✓     |
| `support`   |              ✓             |      ✓     |
| `viewer`    |              ✓             |            |
| `developer` |                            |            |

Every role can read Orders and Carts in the Explorer. Developers see them without
contact details, addresses and extension values.

The account that can deploy the Worker can add the first owner.

## Coming later

`orbcart deploy` (set up an environment in one step) and `npm create orbcart`
(start a new project) are planned, not working commands yet. Until then, see
[Deployment](/deployment).

[Call the HTTP API directly →](/api-reference)