# CLI

> Install the biticaret CLI, start themes and apps, sign in, upload app versions, and give coding agents an MCP server.

The `biticaret` CLI creates, checks, builds and uploads themes and apps. This page documents every command, flag and exit code.

## Install the CLI

CLI downloads are not published yet; they will be provided with the partner programme. Once you have the `biticaret` binary, place it on your `PATH`. `biticaret version` prints the installed version.

## Start a theme

```bash
biticaret theme init my-theme
```

This creates `./my-theme` (or `./skeleton-theme` if no name is given) from biticaret's skeleton theme: every page type with plain markup and minimal CSS, MIT-licensed, with an `AGENTS.md` for AI agents. The CLI clones the theme at the tag matching its own version (`v<version>`). `--clone-url <git url>` clones the default branch of another repository instead. The command refuses a non-empty folder unless `--force` is passed. Cloning requires `git` on your `PATH`.

Next, run `biticaret theme check`, zip the theme folders, and upload the archive in the admin under **Online Mağaza > Temalar** (Online store > Themes).

## Check and convert a theme

```bash
biticaret theme check my-theme [--strict] [--json]
biticaret theme convert their-theme [--out <dir>] [--dry-run] [--json] [--report <file>]
```

- `theme check` runs the upload checks on a theme folder or a ZIP. `--strict` treats warnings as errors. `--json` prints the report as JSON.
- `theme convert` takes a theme written for another platform, rewrites platform-specific names to biticaret equivalents, and removes unsupported calls. It writes in place—or into an empty or new folder with `--out`—and reports every change with its file and line. `--dry-run` reports changes without modifying files. `--report` writes the JSON report to a file as well. Run `theme check` afterwards to see what remains to fix; `theme convert` exits with `1` if any items still require manual fixes.

## Start an app

```bash
biticaret app init my-app
biticaret app init my-blocks --template theme-blocks
```

This creates `./my-app` (the default name) from a starter project. By default this is a small Go app featuring OAuth installation, the mandatory privacy webhooks, and an admin page built with App Bridge. `--template` starts from an example app instead: `theme-blocks`, `functions` or `ui-extensions`. `--clone-url <git url>` clones the default branch of another repository. The command refuses a non-empty folder unless `--force` is passed. It then runs `app check` in the new folder and prints the next steps.

## Sign in

```bash
biticaret auth login [--platform <admin url>] [--no-browser]
biticaret auth status [--platform <admin url>]
biticaret auth logout [--platform <admin url>] [--org <id|name> | --all]
```

`auth login` displays a verification code and opens the partner portal's approval page, where an organisation member authorised to work on apps approves it. Each login belongs to the organisation of the member who approved it. The CLI stores one session per platform and organisation, so you can be signed in to several organisations at once; a new login replaces only the existing session for that organisation.

The CLI stores tokens in the system keychain (macOS `security`, Linux `secret-tool`) or, where none is available, in a file readable only by you. It never prints tokens. Access tokens last 2 hours and refresh tokens 30 days; the CLI refreshes them automatically as needed.

- `auth status` lists active sessions with their organisation, email, role and expiry. Exits with `1` when not signed in.
- `auth logout` revokes the session on the platform and removes its stored tokens. If you are signed in to several organisations, specify one with `--org` or sign out of all of them with `--all`.
- `--no-browser` prints the approval URL instead of opening a browser.
- The platform defaults to `--platform`, then `$BITICARET_PLATFORM`, then `https://admin.biticaret.com.tr`. App commands default to the platform of your most recent login.

## Work on an app

```bash
biticaret app check [dir] [--config <env>] [--json]
biticaret app build [dir] [--config <env>] [--out <dir>] [--skip-build]
biticaret app generate extension --type function --name tier-discount [dir]
biticaret app config use [<env> [dir]]
biticaret app config link [dir] [--config <env>] [--client-id <id> | --name <name> [--handle <handle>]] [--org <id|name>] [--force]
biticaret app deploy [dir] [--config <env>] [--version <name>] [--message <changelog>] [--submit] [--skip-build] [--org <id|name>] [--json]
biticaret app versions list [dir] [--config <env>] [--org <id|name>] [--json]
```

If `dir` is omitted, commands operate on the current working directory. `--config <env>` selects `biticaret.app.<env>.toml` ([Environments](apps/configuration.md#use-environments)).

- `app check` builds the manifest and bundle from the configuration files and runs all checks that do not require platform state. It prints each problem as `file:line: key: message`; `--json` outputs JSON.
- `app build` runs each function's `[build] command`, checks the output, and writes `manifest.json` and `bundle.zip` to `.biticaret/build/` (or `--out`). `--skip-build` skips build commands and packs existing `.wasm` files as-is.
- `app generate extension` scaffolds `extensions/<name>/` from the template for `theme`, `function`, `ui_extension` or `web_pixel`.
- `app config use <env>` makes subsequent commands run without `--config` use `biticaret.app.<env>.toml`. `app config use default`, or omitting the environment, switches back to `biticaret.app.toml`.
- `app config link` selects an existing app in your organisation—or creates a new one—and writes `biticaret.app.toml` from its newest version. `--client-id` links that app non-interactively. `--name` (with optional `--handle`) creates a new app non-interactively. Overwriting an existing file requires `--force`. If you are signed in to several organisations, creating a new app requires `--org` (in an interactive terminal, the CLI prompts you).
- `app deploy` builds and checks the app like `app build`, then uploads a draft version. If `--version` is omitted, the platform assigns `<handle>-<n>`. `--submit` submits it for review immediately. This command is the only way to create a version: the partner portal's **Sürümler** (Versions) tab lists versions and submits drafts, but cannot upload bundles.
- `app versions list` lists the app's versions, newest first, along with their review status.

App commands authenticate using the session of the organisation that owns the config file's `client_id`; `--org` overrides it. `check`, `build`, `generate` and `config use` work offline; `config link`, `deploy` and `versions list` require `auth login`. Keep `.biticaret/` out of git.

## List store themes

```bash
biticaret theme list --store <store handle> [--platform <admin url>] [--org <id|name>] [--json]
```

Lists the themes of one of your organisation's development stores: the theme ID (the value of `?preview_theme_id=` in the preview URL), name, `published` or `unpublished` status, and preview URL. `--json` outputs the same fields plus `updated_at` as JSON. Requires `auth login` and uses the session of the organisation that owns the store (`--org` overrides it). Only development stores are accessible: stores created for client transfer, stores belonging to other organisations, and non-existent handles all return the same "not found" error.

## Work with an AI coding agent

```bash
biticaret mcp
```

Runs a read-only MCP server over stdio for coding agents such as Claude Code or Cursor. The agent launches the server itself; add it to your project's `.mcp.json` (Claude Code) or `.cursor/mcp.json` (Cursor):

```json
{
  "mcpServers": {
    "biticaret": {
      "command": "biticaret",
      "args": ["mcp"]
    }
  }
}
```

In Claude Code, `claude mcp add biticaret -- biticaret mcp` configures the same entry. `biticaret` must be on your `PATH`; otherwise specify its full path as `command`. The agent starts the server in your project directory, which becomes the tools' default `dir`.

The MCP tools only read and validate. They never modify project files, execute functions' `[build] command`, read stored credentials, or make platform API calls—so an agent cannot deploy versions or alter a store through this server, and `app deploy` remains a command you run yourself.

| Tool | What it returns |
| :--- | :--- |
| `docs_search` | The documentation pages best matching `query` (`limit`: default 5, max 20), or all pages when `query` is omitted. |
| `docs_read` | The Markdown source of a single page (`page`). |
| `config_schema` | The keys and types of `biticaret.app.toml` and each extension type's `biticaret.extension.toml` (`file`: `app`, `theme`, `function`, `ui_extension`, `web_pixel`). |
| `manifest_schema` | Every field of `manifest.json` and its type. |
| `reference_lists` | Allowed app identifiers (scopes, webhook topics, extension targets, function and extension types) and theme Liquid filters, tags, globals and objects. `list` selects one list. |
| `app_api_routes` | App API routes with HTTP method, path, required scope and pagination support. `scope` filters to routes requiring that scope. |
| `theme_check` | The `theme check --json` report (`dir`, `strict`). |
| `app_check` | The `app check --json` result (`dir`, `config`). |
| `liquid_render` | Renders a theme template (`template`) with its layout, or a Liquid snippet (`source`), using sample store data. Returns the rendered output, any Liquid issues found beforehand, and any render error. Nothing is persisted. |

The docs tools fetch `https://dev.biticaret.com.tr/llms-full.txt` without sending credentials and cache it in your user cache folder for 24 hours. Offline, they fall back to the cached copy and note its date; if no cache exists, the docs tools return an error while all other tools continue working. Set `BITICARET_DOCS` to point them at another docs site URL or a built docs folder containing `llms-full.txt`.

`mcp` exits with `0` when its input closes, and with `2` on invalid usage or if writing output fails. Validation issues found by the tools appear in their responses, not in the exit code.

## Exit codes

| Code | Meaning |
| :--- | :--- |
| `0` | Success: checks passed, files were written, or the version was uploaded. |
| `1` | Action needed: checks found errors, `theme convert` left items to fix, or the platform rejected the upload or submission. For `auth status`: not signed in. |
| `2` | Invalid usage or execution failure: folder not empty, clone failed, target file already exists, not signed in, platform unreachable, or no app matches the config's `client_id`. |
