> ## Documentation Index
> Fetch the complete documentation index at: https://docs.closient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Closient CLI

> Install the closient command-line client on macOS, Linux or Windows, keep it up to date, and call the Closient API from a terminal or a script.

`closient` is the command-line client for the Closient API. It logs in through
your browser, resolves GTINs through the GS1 Digital Link resolver, and
exports printable label sheets. It works the same for a person at a terminal
and for an agent or CI job: when its output is not a terminal it prints JSON
and never prompts.

## Install

<Tabs>
  <Tab title="Homebrew (macOS, Linux)">
    ```bash theme={null}
    brew install closient/tap/closient
    closient --version
    ```
  </Tab>

  <Tab title="Install script (macOS, Linux)">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/closient/cli/main/install.sh | sh
    closient --version
    ```

    The script installs the binary to `~/.local/bin` without `sudo`, and
    tells you how to add that directory to your `PATH` if it is not there
    already.
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    irm https://raw.githubusercontent.com/closient/cli/main/install.ps1 | iex
    closient --version
    ```

    The script installs the `closient` executable to `%LOCALAPPDATA%\Programs\closient`
    without administrator rights and adds that directory to your user `PATH`.
    Open a new terminal to pick it up.
  </Tab>
</Tabs>

Every release is published at
[github.com/closient/cli/releases](https://github.com/closient/cli/releases):
one archive per platform (macOS on Apple silicon and Intel, Linux on x86\_64
and arm64, Windows on x86\_64) and a `SHA256SUMS` file. Both install scripts
check the download against `SHA256SUMS` and stop with nothing installed if it
does not match. The Linux binaries are statically linked, so they run on any
distribution.

The install scripts read three optional environment variables:

| Variable | Effect |
| - | - |
| `CLOSIENT_INSTALL_DIR` | Install to this directory instead of the default. |
| `CLOSIENT_VERSION` | Install this version (for example `0.1.0`) instead of the latest. |
| `CLOSIENT_RELEASES_URL` | Download from a mirror of the releases page instead of GitHub. |

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/closient/cli/main/install.sh | CLOSIENT_INSTALL_DIR="$HOME/bin" sh
```

## Update

How you update depends on how you installed:

```bash theme={null}
brew upgrade closient/tap/closient  # installed with Homebrew
closient update                     # installed with an install script
```

`closient update` downloads the latest release for your platform, checks it
against `SHA256SUMS`, and replaces the installed binary in one step, so an
interrupted update leaves the old version working. On a copy that Homebrew
installed it changes nothing and tells you to run `brew upgrade closient/tap/closient`
instead, so Homebrew stays in charge of its own files.

```bash theme={null}
closient update --check                  # report only; install nothing
closient --format json update --check    # the same, as JSON for a script
```

```json theme={null}
{
  "current": "0.1.0",
  "latest": "0.1.1",
  "update_available": true,
  "updated": false,
  "installed_via": "standalone",
  "path": "/home/me/.local/bin/closient",
  "message": "closient 0.1.1 is available (you have 0.1.0); run `closient update`"
}
```

### The update notice

At most once a day, a command run at a terminal prints a line to stderr when
a newer release exists:

```text theme={null}
closient 0.1.1 is available (you have 0.1.0); run `closient update` to update
```

The check runs in the background and never slows down or fails the command
you ran; if it cannot reach the releases page, you see nothing. It is never
shown in JSON output, when stderr is not a terminal (a pipe, a script, an
agent), or when the `CI` environment variable is set. To turn it off, set:

```bash theme={null}
export CLOSIENT_NO_UPDATE_NOTIFIER=1
```

## Uninstall

```bash theme={null}
brew uninstall closient                  # Homebrew
rm ~/.local/bin/closient                 # install script, macOS and Linux
```

On Windows, delete `%LOCALAPPDATA%\Programs\closient` and remove it from your
user `PATH`. Your login and settings live in the configuration directory
(`~/.config/closient`, or `%APPDATA%\closient` on Windows); run
`closient auth logout` first to revoke the login on the server.

## Log in

```bash theme={null}
closient auth login
```

The CLI shows a one-time code and opens the approval page in your browser,
using the OAuth 2.0 device authorization grant. Check that the code matches,
allow access, and the CLI stores the login in your system keychain. Use
`--no-browser` to print the link instead of opening it, for example over SSH.

For CI and agents, create an organization API key in the dashboard and set it
in the environment; it takes precedence over any stored login:

```bash theme={null}
export CLOSIENT_API_KEY=csb_...
closient auth status
```

See [Authentication](/authentication) for how API keys and OAuth logins
differ.

## Commands

Every public API operation has a command. The ones below are written by hand
and linked to their request and response reference; every other operation is a
[generated command](#generated-commands). Global flags: `--base-url` (default
`https://www.closient.com`), `--format json|table`, and `--timeout SECS`.

| Command | What it does | API operation |
| - | - | - |
| `closient auth login` | Log in through the browser, or store a token from stdin with `--with-token`. | [Authentication](/authentication) |
| `closient auth status` | Show the user and organizations the CLI acts as, and which credential it uses. | [Identify the authenticated caller](/api-reference/account/account/identify-the-authenticated-caller) |
| `closient auth token` | Print the token in use, for `curl` and other tools. | |
| `closient auth logout` | Revoke the stored login on the server and forget it. | [Authentication](/authentication) |
| `closient resolve <GTIN>` | Show the product behind a GTIN; `--linkset` returns every link the resolver publishes. | [Digital Link resolution](/guides/digital-link-resolution) |
| `closient labels export` | Render a printable PDF label sheet and download it. | [Submit a bulk label-export job](/api-reference/products/labels/submit-a-bulk-label-export-job) |
| `closient labels status <JOB_ID>` | Show an export job, or wait for it and download its PDF with `--output`. | [Poll a bulk label-export job](/api-reference/products/labels/poll-a-bulk-label-export-job) |
| `closient labels templates` | List the label stock you can pass to `labels export --template`. | [List label sheet templates](/api-reference/products/labels/list-label-sheet-templates) |
| `closient api <METHOD> <PATH>` | Send any request to the API, like `gh api`: `-f`/`-F` fields, `--input` for a JSON body, `-H` headers. | [API reference](/api-reference/overview) |
| `closient update` | Update closient to the latest release. | |

Run `closient <command> --help` for every option.

```bash theme={null}
closient resolve 012345678905
closient labels export --scope lots --output lots.pdf
closient --format json labels templates --query avery
closient api GET /account/api/v1/whoami
```

### Generated commands

Every other operation in the [API reference](/api-reference/overview) is
`closient <resource> <verb>`. The resource is the operation's group in
kebab-case (`products`, `api-keys`, `epcis`), and the verb is `list`, `view`,
`create`, `edit`, `delete`, or the operation's own action
(`products upload-image`). `closient --help` lists the resources,
`closient products --help` their verbs, and
`closient products upload-image --help` the flags.

## Output and errors

Results go to stdout and errors to stderr. At a terminal the output is a
table; otherwise, or with `--format json`, it is JSON with a fixed key order.
An error in JSON mode is one object with a stable `code`, a `message`, and the
`exit_code` the process exits with, so a script can branch on either:

| Exit | Meaning |
| - | - |
| 0 | Success |
| 1 | Internal error or unexpected response |
| 2 | Invalid input, caught before any request |
| 3 | Not logged in, the login expired, or the credential was refused (HTTP 401/403) |
| 4 | Not found (HTTP 404/410) |
| 5 | Request refused (HTTP 400/409/422) |
| 6 | Rate limited (HTTP 429); see `retry_after` |
| 7 | Server error (HTTP 5xx) |
| 8 | Network error: DNS, connect, TLS or timeout |
| 9 | The export job failed; `details.job_id` names it |
| 10 | The export job outlived `--wait-timeout`; `details.job_id` names it |

When the API sends an error code, the CLI passes it through as `code`; those
are listed in [Errors](/errors).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.