Skip to main content
closient is the command-line client for the Closient API. Three steps take you from nothing to a printable 2D barcode: install, log in, and make your first barcode. 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

Pick the section for your system. Each one has everything you need to install, update and remove closient that way.

Linux

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. The Linux binaries are statically linked, so they run on any distribution, on x86_64 and arm64. Update:
Uninstall:

macOS with Homebrew

Update:
Uninstall:
Homebrew owns this copy, so closient update leaves it alone and tells you to run brew upgrade instead.

macOS without Homebrew

The script installs the binary to ~/.local/bin without sudo, for Apple silicon or Intel, and tells you how to add that directory to your PATH if it is not there already. Update:
Uninstall:

Windows

In PowerShell:
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, then check it:
Update:
Uninstall: delete %LOCALAPPDATA%\Programs\closient and remove it from your user PATH (Settings, then “Edit environment variables for your account”).

Log in

The CLI prints a one-time code and opens the approval page in your browser:
Sign in on that page with Google, Microsoft or LinkedIn. If you have never used Closient, signing in creates your account. Check that the code matches, choose Continue, then Allow access, and the terminal finishes:
Use --no-browser to print the link without opening it, for example over SSH, and open it on any device. A login acts as you for one organization. If you belong to more than one, the approval page asks which one before Allow access; with one, it names it. closient auth status shows the organization in its organization row. To act for a different organization, run closient auth login again and choose it. An older login that isn’t tied to an organization still works while you belong to one. Once you belong to several, a request that needs an organization exits 5 (HTTP 409) and asks you to log in again. A barcode is a picture of a product your organization has in Closient, so you need an organization first. A login without one ends with the command that creates one. Create one from the terminal and you become its owner:

Make your first barcode

Add one of your own GTINs (8, 12, 13 or 14 digits) as a product, then render its barcode:
qr.svg is a QR code carrying the GS1 Digital Link for that GTIN, HTTPS://GTIN.ONE/01/09506000134352, so a phone camera that scans it lands on Closient’s page for that product. 09506000134352 is GS1’s example GTIN. If the GTIN is already in Closient, products create says so; use closient products claim 09506000134352 instead. The barcode works as soon as the product is yours, before the claim is verified. The file’s extension picks the format: .svg (the default), .pdf, .eps, .png or .tif. SVG, PDF and EPS are vector and print sharp at any size, and print shops should get PDF or EPS. PNG and TIF are raster fallbacks for screens or tools that cannot take vector. --symbology picks the symbol: qr (the default), datamatrix, gs1_128 and the retail linear symbols. A lot or a serial number gets its own barcode once you have stored it, and the Digital Link carries its lot, serial and expiry date:
<LOT_ID> is the id that create-lot prints. A command that cannot write the extension’s format (a DataMatrix has no .tif) stops before sending anything, and so does a --format that contradicts the extension. With any other extension, or when the output goes to a pipe, the command uses --format or the API’s default. The CLI refuses to overwrite an existing --output file; add --force to replace it.

Commands

Every public API operation has a command. The ones below are linked to their request and response reference; every other operation is a generated command. Global flags: --base-url (default https://www.closient.com), --output-format json|ndjson|table, and --timeout SECS. Run closient <command> --help for every option.

Generated commands

Every other operation in the API reference 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.

Preview a write, and read a command’s schema

Every command that writes takes --dry-run. It checks your flags, prints the request it would send as JSON, and sends nothing. Your credential is shown as <redacted>.
closient schema describes a command’s parameters as JSON without calling the API. Run it with no arguments to list the resources, with a resource to list its commands, and with a resource and a command for the method, path, and every parameter with its flag, type, allowed values and whether it is required:

CI and agents

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:
closient context prints a short guide for AI agents, built into the binary: authenticate from the environment, read closient schema before guessing a flag, preview every write with --dry-run, trim reads with --fields and --output-format ndjson, and leave deletes to a person. It needs no credential or network, so an agent can load it at the start of a session:
See Authentication for how API keys and OAuth logins differ.

Install options

Every release is published at 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 install scripts read three optional environment variables:
Your login and settings live in the configuration directory (~/.config/closient, or %APPDATA%\closient on Windows). Before you uninstall, run closient auth logout to revoke the login on the server.

How updates work

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.

The update notice

At most once a day, a command run at a terminal prints a line to stderr when a newer release exists:
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:

Output and errors

Results go to stdout and errors to stderr. At a terminal the output is a table; otherwise, or with --output-format json, it is JSON with a fixed key order. --output-format ndjson prints one compact JSON line per item of a list (a paginated list without its pagination envelope), so a script can read the results line by line; with --limit or --all each page is written as it arrives. --output-format ndjson on a command that returns one object prints that object on one line. To keep a result small, a generated read command takes --fields id,gtin: each item keeps only those keys (a dotted path such as brand.name reaches into an object), and a list keeps its pagination. A name no item has is an error (unknown_field), so a misspelling is never read as an empty column. 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: When the API sends an error code, the CLI passes it through as code; those are listed in Errors.

Deprecation warnings

When an operation the CLI calls is deprecated, the API says so in response headers (Deprecation, Sunset, and Link relations naming the migration guide and the replacement). The CLI prints a warning to stderr, once per command and endpoint in a run, and leaves stdout unchanged:
  • Within 30 days of the retirement date the line starts error: SUNSET IN N DAYS:. The command still succeeds.
  • If the retirement date has passed but the API still answers (any status other than 410), the line starts error: SUNSET PASSED on <date>:. The command’s output and exit code are unchanged: the server served the request, and a write may already have happened.
  • Once the API answers 410 Gone, the CLI exits 11 with the code endpoint_retired and a message naming the replacement.
  • The upgrade hint comes from the update notice’s last check, so it names the newer release and the right upgrade command when one is known. The CLI makes no extra network call, and sends nothing back.
  • If the API reports a newer major version than this CLI was built for, the CLI says so once.
  • In JSON mode each warning is one compact line, {"warning": {"code": "deprecated_endpoint", "level": "warning", "message": ..., "details": {...}}}, with endpoint, sunset, days_left, successor and migration_guide in details. The codes are deprecated_endpoint, endpoint_sunset_soon, endpoint_sunset_passed and newer_api_version; endpoint_retired is the exit-11 error.
To silence the warnings, for example in a script you have already migrated, set:
It silences warnings only, including SUNSET PASSED; a retired operation still exits 11 with its error.

Scripting and pipelines

Without --output, a barcode’s bytes go to stdout and nothing else does, so you can redirect them to a file or pipe them into another tool. Errors go to stderr. With --output PATH, stdout instead carries a summary of the file it wrote (path, bytes, content_type). Redirect to a file:
Pipe into a converter, here CairoSVG turning the SVG into a PDF:
The CLI never prints a barcode to a terminal. With neither --output nor a redirect, it stops with exit 2 and binary_output, whatever the format. A failed request writes nothing to stdout, so in a pipeline the next tool gets empty input. Run with set -o pipefail, or check the CLI’s own exit status (${PIPESTATUS[0]} in bash), rather than the last command’s. Exit 0 means the bytes are complete. 3 means log in again or fix the key, 4 means the product isn’t one your organization stores, and 5 means the API refused the options. The full list is in the table above.