Skip to content
biticaretdevelopers

Getting started

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

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

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

biticaret app init my-appbiticaret 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

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

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).

  • 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

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

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.