Square CLI

The Square CLI brings the public Square API to your terminal and your AI agents, with a consistent command structure and browser OAuth login.

The Square CLI (square) gives you and your AI agents command-line access to the public Square API — catalog, orders, payments, customers, inventory, and more. Every command follows a predictable shape, square <domain> <resource> <verb>, and returns structured output you can pipe, filter, and hand to a model.

The CLI is designed to work well with AI assistants: it ships a machine-readable command manifest (--llms), JSON Schema for every command (--schema), and skill files you can sync into your agent.

Releases, the license, and third-party notices are published at GitHub - square/cli. The Square CLI is proprietary software, and your use is subject to the Square Developer Terms of Service. Run square about to print the license notice.

The Square CLI is published to npm. Install it globally, or run it on demand with npx. You need Node.js installed.

npm install -g @square/cli
square --version

npx -y @square/cli --help

Prebuilt binaries for macOS, Linux, and Windows are attached to each GitHub release, so you don't need Node.js. Download the binary for your platform and checksums.txt from the same release, verify the download, and put the binary on your PATH. For example, on an Apple silicon Mac:

shasum -a 256 --check --ignore-missing checksums.txt
chmod +x square-darwin-arm64
xattr -d com.apple.quarantine square-darwin-arm64   # only if you downloaded it in a browser
sudo mkdir -p /usr/local/bin
sudo mv square-darwin-arm64 /usr/local/bin/square

The Linux binaries require glibc (for example, Debian or Ubuntu). Alpine and other musl-based distributions aren't supported.

If you redistribute a binary, include THIRD-PARTY-NOTICES.md from the same release.

The CLI signs in with your Square account through browser OAuth, so there's no access token to create or manage. Run square auth status at any time to see which endpoint and credential the next command would use.

square auth login

This opens your browser, prompts you to sign in and authorize the Square CLI, and captures the response on a localhost callback (OAuth with PKCE). The CLI exchanges the result for a delegated access token and refresh token, scopes them to a merchant, and stores them at ~/.config/square-cli/credentials.json with mode 0600. The short-lived access token is refreshed automatically; when the grant eventually lapses, run square auth login again.

The OAuth callback listens on the machine running the CLI. To sign in on a remote machine over SSH, forward the callback port, run square auth login --no-open on the remote machine, and open the printed URL in your local browser:

ssh -L 5000:localhost:5000 REMOTE_HOST
square auth login --no-open   # run on the remote machine

Sign out by removing the stored credentials:

square auth logout

The CLI doesn't accept access tokens. It ignores the SQUARE_ACCESS_TOKEN environment variable, and square auth login has no token option. To call Square from CI or a server with an access token, use the Square API directly.

Every business command follows the same shape:

square <domain> <resource> <verb> [args] [options]

For example:

square catalog item list --limit 10
square payments payment get PAYMENT_ID
square orders order search --location-ids LOCATION_ID
square customers customer list --limit 10

Run --help at any level to explore what's available:

square --help                 # list every domain
square catalog --help         # list catalog resources
square catalog item --help    # list verbs and options for catalog items

For the complete list of commands, see the Command reference.

Data goes to stdout; diagnostics go to stderr. Commands print JSON by default. Choose another format with --format:

square catalog item list --limit 1                 # JSON (the default)
square catalog item list --limit 1 --format toon   # compact and token-efficient

For example, square catalog item list --limit 1 --format json returns the matching catalog objects. When more results are available, the response includes a cursor and the command to fetch the next page. Without --format, an interactive terminal prints that command as a hint below the JSON instead. This sample is trimmed: real responses include every field the command selects, with null for fields that have no value.

{
  "objects": [
    {
      "type": "ITEM",
      "id": "W62UWFY35CWMYGVWK6TWJDNI",
      "updatedAt": "2026-10-01T17:32:08.112Z",
      "version": 1760400000000,
      "isDeleted": false,
      "presentAtAllLocations": true,
      "itemData": {
        "name": "Cold Brew",
        "description": "Steeped for 18 hours.",
        "isTaxable": true,
        "productType": "REGULAR",
        "variations": [
          {
            "type": "ITEM_VARIATION",
            "id": "AII5KSYPCHGM63VK4TSY3PMS",
            "version": 1760400000000,
            "isDeleted": false,
            "presentAtAllLocations": true,
            "itemVariationData": {
              "itemId": "W62UWFY35CWMYGVWK6TWJDNI",
              "name": "Regular",
              "ordinal": 0,
              "pricingType": "FIXED_PRICING",
              "priceMoney": {
                "amount": 450,
                "currency": "USD"
              },
              "sellable": true,
              "stockable": true
            }
          }
        ],
        "isArchived": false
      }
    }
  ],
  "cursor": "Y2F0YWxvZy1pdGVtcy1wYWdlLTI",
  "matchedVariationIds": null,
  "cta": {
    "description": "Next page:",
    "commands": [
      {
        "command": "square catalog item list --cursor Y2F0YWxvZy1pdGVtcy1wYWdlLTI --limit 1"
      }
    ]
  }
}

Prune large responses to just the fields you need with --filter-output (dot notation, comma-separated paths, [] for every array element, [start,end] array slices). Paths start at the top of the response, so list results sit under objects[]:

square catalog item list --filter-output 'objects[].id,objects[].itemData.name'

{
  "objects": [
    {
      "id": "W62UWFY35CWMYGVWK6TWJDNI",
      "itemData": {
        "name": "Cold Brew"
      }
    },
    {
      "id": "LBTYIHNHU52WOIHWT7SNRIYB",
      "itemData": {
        "name": "Croissant"
      }
    },
    {
      "id": "2ICQ7LKTH6RHWJ4EPBQZYQ44",
      "itemData": {
        "name": "Latte"
      }
    }
  ]
}

The same filter with --format toon:

objects[3]:
  - id: W62UWFY35CWMYGVWK6TWJDNI
    itemData:
      name: Cold Brew
  - id: LBTYIHNHU52WOIHWT7SNRIYB
    itemData:
      name: Croissant
  - id: 2ICQ7LKTH6RHWJ4EPBQZYQ44
    itemData:
      name: Latte

For a single object, paths start at the object itself:

square catalog item get OBJECT_ID --filter-output id,itemData.name,itemData.productType
square catalog item get OBJECT_ID \
  --filter-output 'itemData.variations[0,5].itemVariationData.priceMoney,itemData.taxIds[0,3]'

The Square CLI is built to be driven by AI assistants. It doesn't run as an MCP server; to connect an MCP client to Square, use the Square MCP server.

square --llms --format json         # every command and its description
square catalog item list --schema   # JSON Schema for one command's args, options, and output

The CLI ships task-oriented skill files you can sync into your agent:

square skills list
square skills add

Skills install globally by default. Pass --no-global to install them into the current project instead.

To build and deploy a seller web app, use the apps skill and the square apps commands. Sign in with a production seller account first, because the apps platform runs in production only:

square skills add --no-global
square apps site --help

The CLI covers the public Square API. Run square --help to list every domain, or see the Command reference for the complete list of commands. Common domains include: