Downloading the command-line client

This page is for anyone who needs the cadence command-line client on a machine. It covers how to get the client from your Cadence instance, which file to take, how to check it, and what each refusal means.

Your instance offers the client for download only if it has been set up to. On an instance that has not, the user menu has no Download CLI item, the /cli page answers 404 Not Found, and the MCP tool and HTTP route below refuse with "This Cadence instance does not offer CLI downloads." In that case get the client from whoever operates your instance.

Replace https://cadence.example.com with your instance's address. Version tags such as v1.4.0 on this page are invented examples.

Over MCP

cli_releases_get is a tool on Cadence's MCP endpoint: you call it with tools/call, authenticated with your own bearer token (see Authentication). It returns everything you need to install or update the client: one release's files, each with a download link, its SHA-256 and its size, and the list of published versions.

cli_releases_get is an operator tool: tools/list shows it when you authenticate as yourself. A worker working a lease gets the worker list instead, which does not include it (see MCP § tools/list). It is not tied to a space, so you need no role in any space to call it. It is listed whether or not your instance offers downloads, so a call on an instance that does not is refused with a message rather than missing.

The result looks like this:

{
  "version": "v1.4.0",
  "latest": "v1.4.0",
  "versions": ["v1.4.0", "v1.3.2", "v1.3.1"],
  "assets": [
    {
      "os": "darwin",
      "arch": "arm64",
      "url": "https://…",
      "sha256": "…",
      "size": 61022208
    },
    { "os": "darwin", "arch": "x64", "url": "https://…", "sha256": "…", "size": 63291392 },
    { "os": "linux", "arch": "arm64", "url": "https://…", "sha256": "…", "size": 60149760 },
    { "os": "linux", "arch": "x64", "url": "https://…", "sha256": "…", "size": 62717952 }
  ],
  "checksums_url": "https://…",
  "expires_at": "2026-10-10T12:15:00Z",
  "install": "Install or update the Cadence CLI (latest: v1.4.0).\n\n0. Run `cadence version`. …"
}

The links last 15 minutes. After expires_at, call cli_releases_get again for fresh ones.

When the call is refused

A refused call returns invalid arguments (code -32602, see MCP § Error codes) with one of these messages:

In the browser

On an instance that offers downloads, open the user menu: the avatar at the right of the top navigation. Choose Download CLI. It sits below User settings, and above Instance settings if you are an instance administrator. The item is not there on an instance that does not offer downloads.

Download CLI opens https://cadence.example.com/cli. Any signed-in user can open it; you need no role in a space. If you are not signed in, Cadence sends you to sign in first.

The page shows these parts, in order:

1. Install followed by the latest version, for example Install v1.4.0. It says "Download the binary for your platform below, then run these commands from the folder it saved to." and then gives the commands for each platform.

   Before you run them, pick the file for your machine as in Choosing the right file, download it from the version list, and check it as in Checking the file.

   For macOS:

   chmod +x cadence
   mv cadence /usr/local/bin/cadence
   xattr -d com.apple.quarantine /usr/local/bin/cadence
   cadence version

   For Linux:

   chmod +x cadence
   mv cadence /usr/local/bin/cadence
   cadence version

   It ends with "Then sign in with cadence login." See Command-line client § Signing in.

2. Every published version, newest first. The latest has a Latest badge. Under each version is a list of its files, binaries first and then checksums.txt. Each row shows a platform label, the file name as a link, and the file's size.

If the install commands fail:

• mv reports "Permission denied". You cannot write to /usr/local/bin. Run the mv command again with sudo in front.
• mv reports "No such file or directory". /usr/local/bin does not exist on this machine, which happens on some Macs. Create it with sudo mkdir -p /usr/local/bin, then run the mv command again.
• xattr reports that the attribute does not exist. The file was not quarantined. Ignore the error.
• cadence version reports command not found. /usr/local/bin is not on your PATH. Run echo $PATH to check, and add /usr/local/bin to your PATH in your shell's startup file.

Platform labels

The label column shows:

The two x64 files are labelled with their own file name. They are the files for 64-bit Intel and AMD machines.

When the page has nothing to offer

On an instance that offers downloads, the page shows one of these messages in place of the install commands and version list:

• "CLI downloads are unavailable right now. Try again in a few minutes." Cadence could not read the published releases. Reload the page later.
• "No CLI release has been published yet." There is nothing to download yet.

Downloading a file

Click a file name to download it. The link goes to https://cadence.example.com/cli/<version>/<file>, for example /cli/v1.4.0/cadence-linux-arm64. Cadence redirects that request to a download link that works for 5 minutes. A binary saves under the name cadence, whatever platform it is for, so the install commands above work as written.

If a saved download link has expired, go back to the Download CLI page and click the file again. A version or file name that is not published answers 404 Not Found. The same sign-in and instance conditions apply as for the page.

Over the HTTP API

GET /api/v1/cli_releases returns the same result as cli_releases_get. It accepts any bearer token the HTTP API accepts (see Authentication), and it is not tied to a space.

curl "https://cadence.example.com/api/v1/cli_releases?version=v1.4.0" \
  -H "Authorization: Bearer smc_your_token_here"

The response body has the fields described under Over MCP. The links last 15 minutes; request again after expires_at for fresh ones.

Refusals use the standard error body (see HTTP API § Errors):

{
  "error": {
    "code": "not_configured",
    "message": "This Cadence instance does not offer CLI downloads."
  }
}

What to do about each is in When the call is refused.

Choosing the right file

A release has one binary for each of these machines. In assets, os and arch name the machine each one is for:

On a machine where uname -m prints x86_64, take the x64 file. Step 1 of the install text tells you to map x86_64 to amd64, but no published file has arch amd64. Pick the x64 asset instead, then follow the remaining steps.

Checking the file

Before you install a binary, check its SHA-256. Compare it with one of these:

• the sha256 value of its asset in cli_releases_get or GET /api/v1/cli_releases;
• its line in checksums.txt. Each line there is a checksum, two spaces, and a published file name, such as cadence-linux-x64. Use the line for the file you downloaded: the file name you clicked on the Download CLI page, or cadence-<os>-<arch> for the asset you fetched. Your copy is saved as cadence, so compare only the checksum, not the name.

Run this in the folder where you saved the file. If you saved it under a name other than cadence, use that name.

On macOS:

shasum -a 256 cadence

On Linux:

sha256sum cadence

The command prints a checksum followed by the file name. If the checksum does not match, delete the file and do not install it.

Checking which version you have

cadence version prints the version of the client you have installed. If latest from cli_releases_get, or the Latest badge on the Download CLI page, names a newer version, an update is available. See Command-line client § Discovering commands.

Updating the client

The client does not update itself. To update it:

1. Find the copy your shell runs:

   command -v cadence

   It prints a path, such as /usr/local/bin/cadence. If you got your current client from whoever operates your instance, it may be somewhere else.

2. Download the newer file for your machine and check it, as in Choosing the right file and Checking the file.

3. Run the install commands from In the browser. If the path from step 1 is not /usr/local/bin/cadence, use that path in place of /usr/local/bin/cadence in the mv and xattr commands, so the new copy replaces the one your shell runs.

4. Run cadence version and check that it prints the new version.