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
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
- theme check runs the upload checks on a theme folder or a ZIP.
--stricttreats warnings as errors.--jsonprints 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-runreports changes without modifying files.--reportwrites the JSON report to a file as well. Run theme check afterwards to see what remains to fix; theme convert exits with1if any items still require manual fixes.
Start an app
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
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
1when 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
--orgor sign out of all of them with--all. --no-browserprints 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
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;
--jsonoutputs JSON. - app build runs each function's [build] command, checks the output, and writes
manifest.jsonandbundle.zipto .biticaret/build/ (or--out).--skip-buildskips build commands and packs existing.wasmfiles as-is. - app generate extension scaffolds
extensions/<name>/from the template fortheme,function,ui_extensionorweb_pixel. app config use <env>makes subsequent commands run without--configusebiticaret.app.<env>.toml. app config use default, or omitting the environment, switches back tobiticaret.app.toml.- app config link selects an existing app in your organisation—or creates a new one—and writes
biticaret.app.tomlfrom its newest version.--client-idlinks 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
--versionis omitted, the platform assigns<handle>-<n>.--submitsubmits 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
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
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):
{
"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. |