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 removeclosient that way.
Linux
~/.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:
macOS with Homebrew
closient update leaves it alone and tells you
to run brew upgrade instead.
macOS without Homebrew
~/.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:
Windows
In PowerShell:closient executable to %LOCALAPPDATA%\Programs\closient
without administrator rights and adds that directory to your user PATH.
Open a new terminal, then check it:
%LOCALAPPDATA%\Programs\closient and remove it from your
user PATH (Settings, then “Edit environment variables for your account”).
Log in
--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 isclosient <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:
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 aSHA256SUMS 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:
~/.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: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 startserror: 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 codeendpoint_retiredand 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": {...}}}, withendpoint,sunset,days_left,successorandmigration_guideindetails. The codes aredeprecated_endpoint,endpoint_sunset_soon,endpoint_sunset_passedandnewer_api_version;endpoint_retiredis the exit-11 error.
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:
--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.