> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluid.app/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract. > Authenticate with the header Authorization: Bearer ; public storefront read endpoints require no auth. > Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null. > Never use /api/company/v1 or /api/v1 paths, page/per_page params, or offset pagination — they are legacy. > The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas). > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. # Fluid CLI: Local Theme Development and Deployment Tool > Use the Fluid CLI to develop, pull, and push themes locally — with commands for authentication, company switching, and live development servers. The Fluid CLI is a command-line tool that brings your theme development workflow to your local machine. With it, you can pull your live theme down to edit in your preferred code editor, push changes back to the server, run a local development server with hot reload, and manage authentication across multiple company accounts. It is designed for developers who want full control over their theme files outside of the browser-based editor. ## Installation Install the Fluid CLI using either RubyGems or Homebrew: ```bash RubyGems theme={null} gem install fluid_cli ``` ```bash Homebrew theme={null} brew tap fluid-commerce/fluid brew install fluid_cli ``` After installation, verify it is available by running `fluid --version`. ## Authentication Before you can interact with any theme, you need to authenticate the CLI with your Fluid account. ```bash theme={null} fluid login ``` This opens the Fluid authentication flow in your browser. After you approve access, the CLI stores a token locally for future commands. To check which account and company you are currently authenticated as: ```bash theme={null} fluid whoami ``` To sign out and remove the stored token: ```bash theme={null} fluid logout ``` ## Company Management If you manage multiple companies in Fluid, you can switch between them without logging out. Run the interactive company switcher: ```bash theme={null} fluid switch ``` Or switch directly to a specific company by subdomain: ```bash theme={null} fluid switch -c mystore ``` After switching, all subsequent theme commands operate against the selected company's theme. ## Theme Commands Use these commands to manage your theme files between your local machine and the Fluid platform. | Command | Description | | -------------------------------- | --------------------------------------------------------------------------------- | | `fluid theme init` | Initialize a new theme project in the current directory | | `fluid theme pull` | Pull the published theme from the server to your local directory | | `fluid theme pull --nodelete` | Pull from the server, but preserve any local files that don't exist on the server | | `fluid theme push` | Push your local theme files to the server and publish them | | `fluid theme push --unpublished` | Push local files to the server as a draft without publishing | | `fluid theme push --nodelete` | Push local files, but preserve any server files that don't exist locally | | `fluid theme dev` | Start a local development server with live reload | | `fluid theme skills install` | Install the bundled Fluid theme skills for coding agents | ### Examples Pull your current theme before making changes: ```bash theme={null} fluid theme pull ``` Push your local changes as a draft so you can preview before publishing: ```bash theme={null} fluid theme push --unpublished ``` Start the local dev server for active development: ```bash theme={null} fluid theme dev ``` ## Install theme skills Install the bundled theme-development skills so a compatible coding agent can use them: ```bash theme={null} fluid theme skills install ``` The default destination is `.agents/skills/` in your current project. Existing skills remain untouched unless you approve the overwrite. Choose a different destination with `--dir` or `-d`: ```bash theme={null} fluid theme skills install --dir .claude/skills ``` Overwrite existing copies without a prompt with `--force` or `-f`: ```bash theme={null} fluid theme skills install --force ``` Restart your agent session after installation so it can discover the new skills. ## Getting Started Workflow Follow these steps to go from a fresh install to an active local development environment: Install via RubyGems or Homebrew as shown above. Run `fluid login` and complete the browser authentication flow. ```bash theme={null} mkdir my-theme && cd my-theme ``` To start a brand new theme: ```bash theme={null} fluid theme init ``` Or, to download your existing published theme: ```bash theme={null} fluid theme pull ``` ```bash theme={null} fluid theme dev ``` The dev server proxies requests to your local theme files, so you can see changes in the browser instantly as you save. When you're ready to publish: ```bash theme={null} fluid theme push ``` Or push as a draft first to review in the admin: ```bash theme={null} fluid theme push --unpublished ``` `fluid theme dev` is currently only available when the CLI is installed via RubyGems (`gem install fluid_cli`). If you installed via Homebrew and need local dev server support, reinstall using the gem method.