CLI

In CLI mode the app runs without a window: it signs in, opens a workspace and starts the local API (and, optionally, the MCP server). This is useful to keep BOMIST running on a computer (e.g. a server) so scripts, integrations and other computers can use your workspace's data without anyone having to keep the app open.

CLI mode is available on every installation of the app, there's nothing extra to install.

Requirements

• A user to sign in as, whose plan includes the API.
• On Team Workspaces, the user's role must have access to the API (see Role-based Permissions).
• One or more API keys of your choice. Every request made to the API must include one of them.
• The workspace must not be open in the app (or in another CLI mode instance). A workspace can only be used by one process at a time, so if you need to keep using the app on the same computer, open a different workspace there (or a copy of it).

Running it

Start the app with the --cli option and the workspace to open (--ws). The user, their password and the API keys can be passed as options or through environment variables, which is the recommended way so they don't show up in your shell's history:

export BOMIST_CLI_USER_EMAIL=[email protected]
export BOMIST_CLI_USER_PASS=your-password
export BOMIST_CLI_API_KEYS=key1,key2

Then, depending on your operating system:

# Windows
"%LOCALAPPDATA%\Programs\BOMIST\BOMIST.exe" --cli --ws="My Workspace"

# macOS
/Applications/BOMIST.app/Contents/MacOS/BOMIST --cli --ws="My Workspace"

# Linux
bomist --cli --ws="My Workspace"

Once it's running, the API is served at http://localhost:3334 (by default), along with its documentation at http://localhost:3334/_swagger_ui. The default port is different from the app's (3333) so both can run on the same computer.

To stop it, press Ctrl+C (or send it a SIGTERM). The API is stopped and the workspace is closed, just as when quitting the app.

To list all the available options, run the app with --help (e.g. bomist --help on Linux).

Choosing the workspace

--ws takes either the workspace's folder (the one with the workspace.bomist_ws file) or its name (in any case):

• Sample (or --ws-sample): the sample workspace.
• The name of a Local Workspace on this computer (the ones listed on the app's workspace selection).
• The name of one of your Team Workspaces, as long as it has already been opened in the app on this computer. CLI mode doesn't download Team Workspaces, so open it once in the app first.

If no workspace (or more than one) matches the name, the app exits and lists the names it knows.

Options

Option	Description
--ws=<folder or name>	The workspace to open (required, or --ws-sample)
--ws-sample	The sample workspace (same as --ws=Sample)
--auth-email=<email>	The user to sign in as (or BOMIST_CLI_USER_EMAIL). Required
--auth-pass=<password>	The user's password (or BOMIST_CLI_USER_PASS). Required
--api-keys=<key1,key2,...>	The API keys, comma-separated (or BOMIST_CLI_API_KEYS). Required
--api-host=<host>	The API's host. Default: localhost (use 0.0.0.0 to make it reachable from other computers)
--api-port=<port>	The API's port. Default: 3334
--api-rate-limit-req=<n>	Maximum number of requests per client IP in --api-rate-limit-time (both or neither)
--api-rate-limit-time=<time>	The rate limit's time window: in seconds, or 30s, 5m, 1h, etc.
--api-trusted-proxies=<ip or range,...>	Proxies in front of the API whose X-Forwarded-For header is trusted to tell the client's IP (e.g. 10.0.0.0/8)
--ip-allowlist=<ip or range,...>	The only client IPs the API and the MCP server answer
--api-cors=<origins or domains,...>	The origins web browsers may call the API from (instead of BOMIST_API_CORS)
--mcp-port=<port>	Starts the MCP server at this port (or BOMIST_CLI_MCP_PORT)
--mcp-host=<host>	The MCP server's host (or BOMIST_CLI_MCP_HOST). Default: 127.0.0.1 (use 0.0.0.0 to make it reachable from other computers)
--mcp-access-token=<token>	A token the MCP server's clients must send (or BOMIST_CLI_MCP_ACCESS_TOKEN). Optional
--currency=<code>	The preferred currency for prices, totals and quotes (USD, EUR, etc.), instead of the app's
--help	Lists the options

An option always takes precedence over its environment variable.

If something is wrong (a missing option, wrong credentials, a workspace that can't be found or opened, etc.) the app exits with code 1 and tells you why.

Windows

On Windows the app isn't a console program, so it doesn't print anything to the terminal. Check the log files instead, or simply whether the API is answering.

API keys

Every request made to the API must include one of the API keys in the X-BOMIST-CLI-API-KEY header, otherwise it's refused with a 401:

curl -H "X-BOMIST-CLI-API-KEY: key1" http://localhost:3334/parts?limit=10

The API's documentation (/_swagger_ui) doesn't need a key to be opened. To try out requests from it, set your key through the Authorize button.

Having more than one key is useful to give each script or integration its own key, so you can replace one without affecting the others. To help you know which one made each request, keys are identified in the logs by their position in the list and their last 4 characters (keys are never logged in full).

Securing access

When the API is reachable from other computers, you can further restrict who can use it:

• IP allowlist (--ip-allowlist): only the listed IPs or ranges (e.g. 192.168.1.0/24) are answered. Connections from anyone else are dropped without an answer. This applies to the MCP server too. Add 127.0.0.1 if requests from the same computer should also be answered.
• Rate limit (--api-rate-limit-req and --api-rate-limit-time): limits how many requests each client IP can make in a given time window (e.g. --api-rate-limit-req=100 --api-rate-limit-time=1m). Requests over the limit get a 429 with a Retry-After header.
• Trusted proxies (--api-trusted-proxies): if the API is behind a reverse proxy, the client's IP (used by the allowlist and the rate limit) is taken from the X-Forwarded-For header set by the proxy. Proxies on the same computer (e.g. a Cloudflare Tunnel's cloudflared) and Cloudflare's are trusted by default.
• CORS (--api-cors): the origins web browsers may call the API from. A domain (example.com) allows both its https and http origins, *.example.com allows any of its subdomains, and * allows any origin.

MCP server

The MCP server can be started along with the API by setting --mcp-port:

bomist --cli --ws="My Workspace" --mcp-port=3335 --mcp-access-token=my-secret-token

• Its clients don't need an API key. If you set an access token, they must send it as an Authorization: Bearer <token> header. If the MCP server is reachable from other computers, make sure to set one: anyone reaching it without a token would use your workspace as the signed-in user.
• By default it's read-only. To let it make changes to your workspace, set the environment variable BOMIST_CLI_MCP_ALLOW_WRITES=yes before starting the app.
• Its requests follow the same rules as the API's (the user's role, read-only access, the plan).

Sign-in and permissions

The user is signed in on the computer just like when signing in on the app, so the app on that computer will then be signed in as that user too. The sign-in is renewed every hour. If the server can't be reached, CLI mode keeps going with the session it already has for that user.

The API answers with the user's role on the workspace: if the role (or its access to the API) is read-only, only GET requests are allowed. The workspace is also read-only when the Team Workspace isn't active, or when the user hasn't been able to sign in for too long, just like in the app.