> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ollie.shop/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> The ollieshop command line: what it does, how it authenticates, the global flags and output formats every command shares, and the environment variables it reads

`ollieshop` is the command line of Ollie Shop. It runs the local dev server that feeds [Studio](/ollie-shop/studio.md), deploys components and functions, and manages the records behind them (stores, versions, components, functions) without opening the Admin. It is published as `@ollie-shop/cli` and requires **Node.js 22 or newer**.

Projects scaffolded with `npx create-ollie-shop` install it as a dev dependency, so `npx ollieshop <command>` works from the project root and `npm start` runs the dev server. A global install is optional; see [Installation](/ollie-shop/cli/installation.md).

## Commands

| Command | What it does | Login | `ollie.json` |
| - | - | :-: | :-: |
| [`login`](/ollie-shop/cli/installation#logging-in) | Sign in through the browser and store the credentials | | |
| [`start`](/ollie-shop/cli/start) | Dev server for components, connected to Studio | | yes |
| [`whoami`](/ollie-shop/cli/whoami) | Show who you are and which store the project points to | yes | optional |
| [`init`](/ollie-shop/cli/project-config#init) | Write the store and version ids to `ollie.json` | | writes |
| [`setup`](/ollie-shop/cli/project-config#setup) | Migrate legacy `meta.json` files into `ollie.json` | | writes |
| [`deploy`](/ollie-shop/cli/deploy) | Bundle a component or function folder and build it | yes | |
| [`status`](/ollie-shop/cli/deploy#status) | Check or wait for a build | yes | |
| [`store`](/ollie-shop/cli/resources#store), [`version`](/ollie-shop/cli/resources#version), [`component`](/ollie-shop/cli/resources#component), [`function`](/ollie-shop/cli/resources#function) | Create, update and list records | yes | |
| [`business-rule`](/ollie-shop/cli/resources#business-rule) | List, read and update business rules | yes | |
| [`function dev`](/ollie-shop/cli/function-dev) | Run functions locally against a real upstream | | optional |
| [`schema`](/ollie-shop/cli/resources#schema) | Print the JSON schema of a command's input | | |
| `check-update` | Check for a newer CLI release | | |
| `help`, `--version` | Help screen and the installed version | | |

Flags come **after** the subcommand: `ollieshop store create --name "Acme"`, not `ollieshop store --name "Acme" create`.

## Two ways to run

Every command works in a terminal. The record commands (`store`, `version`, `component`, `function`, `business-rule`, `deploy`, `status`, `whoami`, `schema`, `init`, `setup`, `check-update`) are also designed for scripts and coding agents: they take their input as flags or as one JSON document, print one JSON line, and exit non-zero on failure. `login`, `start` and `function dev` are interactive.

## Global flags

| Flag | Meaning |
| - | - |
| `-o`, `--output json\|pretty` | Output format. Without it, output is `pretty` in a terminal and `json` when piped |
| `--dry-run` | Validate the input and print what would be sent, without calling the API. Supported by the create and update commands, `deploy` and `setup`. Runs before authentication, so no login is needed |
| `--fields a,b,c` | Keep only these top-level keys of `data` in the output (or these columns in a pretty table) |
| `-d`, `--data '<json>'` | Pass the whole input as one JSON object instead of flags. When present, the command's own flags are ignored. Keys are camelCase (`storeId`, `versionId`, `onError`) |
| `-s`, `--stage <name>` | Use `ollie.<stage>.json` merged over `ollie.json`. See [Stages](/ollie-shop/cli/project-config.md#stages) |

Flag syntax: `--key value` works everywhere. Every command except `login` and `start` also accepts `--key=value`, and a value that starts with `-` (such as a negative number) needs that `=` form. `login` and `start` only read the two-token form. Boolean flags are passed bare (`--wait`); where a value is accepted, only `true` and `false` are valid.

> [!WARNING]
>
> On `component create` and `component update`, `-s` is the short form of `--slot`, not of `--stage`. Use the long `--stage` on those commands.

## Output

In `json` mode every command prints exactly one line on stdout:

```json theme={"system"}
{"data":{"id":"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"}}
```

Lists return an array under `data`. `deploy`, `status` and the `function` commands also include `"success": true`. A handled error prints `{"error":{"message":"..."}}` on stdout and exits with code 1.

In `pretty` mode objects print as `key: value` lines, lists print as a table, and errors go to stderr as `Error: ...`.

A `--dry-run` prints `{"dryRun":true,"action":"component.create","data":{...}}`.

## Authentication

`ollieshop login` opens the Admin in your browser and stores the resulting session in `~/.ollie-shop/credentials.json`. Commands that talk to the API renew the session automatically when it is about to expire. There is no logout command; delete the credentials file to sign out. Details in [Installation](/ollie-shop/cli/installation.md).

## Environment variables

| Variable | Effect |
| - | - |
| `OLLIE_STAGE` | Default for `--stage` (not read by `init`) |
| `OLLIE_SKIP_UPDATE_CHECK` | Any value disables the update banner |
| `CI` | Any value disables the update banner and the automatic browser open of `start` |

`function dev` also loads a `.env` file, see [its page](/ollie-shop/cli/function-dev.md).

## Updates

Before most commands the CLI checks npm once a day and prints a banner when a newer version exists:

```text theme={"system"}
⚠  Update available: 1.13.1 → 1.14.1
   Run npm i -g @ollie-shop/cli@latest to update.
```

In a scaffolded project update the dev dependency instead: `npm i -D @ollie-shop/cli@latest`. `ollieshop check-update --force` checks immediately and prints the result as data.

## Exit codes

`0` on success, `1` on any handled error (validation, authentication, API, a failed build when waiting). A build that ends in any status other than `SUCCEEDED` is an error for `deploy --wait` and `status --wait`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.