CLI

The seventhings CLI gives you access to the Customer API from your terminal, without writing an API client. It is built on the Go SDK and provides resource commands, a full-screen terminal UI, and structured output for scripts, CI, and AI agents.

• Repository: github.com/SeventhingsCompany/customer-api-cli
• Downloads: GitHub releases

Installation

Linux and macOS

curl -fsSL https://raw.githubusercontent.com/SeventhingsCompany/customer-api-cli/main/install.sh | sh

The installer uses /usr/local/bin if writable, otherwise ~/.local/bin. Make sure the installation directory is on your PATH. To choose a directory:

curl -fsSL https://raw.githubusercontent.com/SeventhingsCompany/customer-api-cli/main/install.sh | sh -s -- --bin-dir ~/bin

Use --version vX.Y.Z to install a specific published version. Run the installer again to update.

Windows

In PowerShell:

irm https://raw.githubusercontent.com/SeventhingsCompany/customer-api-cli/main/install.ps1 | iex

The installer uses %LOCALAPPDATA%\Programs\seventhings and adds it to your user PATH.

Other installation options

The releases include archives for Linux, macOS, and Windows on amd64 and arm64, plus man pages and shell completions. You can also build from source with Go 1.27.1 or newer:

go install github.com/SeventhingsCompany/customer-api-cli/cmd/seventhings@latest

The installers verify downloads against checksums.txt. The Linux/macOS installer also verifies the signature when cosign is installed. See the repository’s verification instructions for manual verification. Review installation scripts before running them if your organization’s security policy requires it.

Log in

Use your instance URL, OAuth client ID, and seventhings username. Pass the instance URL without /customer-api/v1; the CLI handles the API path for you. See Authentication for the underlying authentication flow.

seventhings auth login \
  --url https://your-instance.seventhings.com \
  --client-id your-client-id \
  --username user@example.com

In an interactive terminal, the CLI prompts for your password without echoing it. Tokens are stored in the OS keyring, or in a file with 0600 permissions where no keyring is available. Stored sessions refresh automatically.

seventhings auth status
seventhings auth logout

Multiple instances

Use named profiles to keep each instance’s configuration and tokens separate:

seventhings auth login --profile production \
  --url https://your-instance.seventhings.com \
  --client-id your-client-id --username user@example.com

seventhings config list
seventhings config use production
seventhings objects list --profile production

config use sets the default profile. --profile selects one for a single command; SEVENTHINGS_PROFILE can select it through the environment.

Browse and manage resources

Start with read-only commands:

seventhings objects list --filter 'inventory_name like Laptop' --sort -updated_at
seventhings objects get --barcode 102021
seventhings objects count --filter 'inventory_name like Laptop'

Use --help on any command to discover its arguments and supported flags:

seventhings --help
seventhings objects list --help
seventhings describe

Command group	What you can do
objects	List, count, get by UUID or barcode, create, update, delete, archive, unarchive, manage file attachments, and view history
rooms, locations	List, count, get, create, update, delete, and view history
persons	List, count, get by UUID or numeric ID, create, update, delete, create a user, and view history
users	List and get users
tasks	List, get, create, update, set status, delete, and view history
rental-cases	List, get, create, update, delete, and view history
files	List, get, upload, download, and save thumbnails
fields	List field definitions, discover mandatory or missing fields, get, create, and update
hub items, hub orders	Work with CircularityHub items and orders
reports	List templates and create PDF reports
api <METHOD> <path>	Call an endpoint directly
auth, config	Manage authentication and profiles

Write requests

Use repeatable --set flags for fields, or --data for a JSON body. --data accepts inline JSON, @filename, or - to read from stdin.

Preview a request before sending it:

seventhings objects create \
  --set inventory_name=Laptop --set barcode=SN-1 --dry-run

Remove --dry-run only when you intend to create the record. Field keys and mandatory fields depend on your instance; inspect seventhings fields --help before constructing a payload. Use key:=json rather than key=value when a field needs a JSON value instead of a string.

Destructive actions ask for confirmation in interactive mode. In agent mode, they require --yes, including raw api DELETE requests. --yes confirms the action; it is not a preview.

Downloads, thumbnails, and reports refuse to replace an existing output file unless you pass --overwrite.

Interactive terminal UI

Run the CLI without arguments in an interactive terminal, or use ui:

seventhings
seventhings ui

The full-screen UI has tabs for resources and a Settings tab for profiles, page size, and rate limit. Your terminal must be at least 40 columns by 16 rows.

Key	Action
↑ / ↓	Select a row
j / k	Next / previous page in resource lists; scroll in detail views
s or /	Search
f	Set filters and sort on supported resources
enter	Open details
h	View history
y / Y	Copy the record ID / CLI command for the current view
p	Hide or show pictures
,	Open Settings
?	Show all keyboard shortcuts

Picture rendering is detected automatically. Set SEVENTHINGS_IMAGES=off to disable it, or consult the CLI README for supported terminal image protocols and additional controls.

Scripts, CI, and AI agents

Agent mode never prompts. It returns structured output on stdout, JSON errors on stderr, and stable exit codes. Enable it explicitly with --agent or SEVENTHINGS_MODE=agent. It is also selected with CI=true, or automatically when stdin or stdout is not a terminal.

Supply credentials through your CI secret store or environment. For example, with an existing access token:

export SEVENTHINGS_BASE_URL=https://your-instance.seventhings.com
# Supply SEVENTHINGS_TOKEN securely through your environment or CI secret store.
seventhings --agent objects list --output json

Environment variable	Purpose
SEVENTHINGS_BASE_URL	Instance URL
SEVENTHINGS_TOKEN	Existing access token; not refreshed automatically
SEVENTHINGS_USERNAME, SEVENTHINGS_PASSWORD, SEVENTHINGS_CLIENT_ID	Log in without a stored session
SEVENTHINGS_PROFILE	Profile name
SEVENTHINGS_MODE	agent or interactive
SEVENTHINGS_RATE_LIMIT	Requests per minute; default 200, 0 disables the client-side limit

Do not commit credentials or tokens to scripts or print them in CI logs. For non-interactive auth login, use SEVENTHINGS_PASSWORD or --password-stdin instead of a password prompt.

Structured output

Use --output (or -o) to select json, ndjson, yaml, or table. --fields keeps selected top-level fields; --jq filters output, and --raw prints string results without quotes.

# Export all pages with an explicit newline-delimited JSON format.
seventhings --agent objects list --all --output ndjson \
  --fields asset_uuid,barcode > objects.ndjson

# Discover the complete machine-readable command, flag, and exit-code catalog.
seventhings --agent describe

Errors and exit codes

Agent-mode errors are a single JSON line on stderr with an error object containing a code, exit code, and message, plus HTTP details when available.

Exit code	Meaning
0	Success
1	Generic or network error
2	Invalid arguments, missing input, or required --yes
3	Not logged in, or HTTP 401/403
4	Not found
5	Validation error: HTTP 400/409/422
6	Rate limited after retries
7	Server error
8	Partial success: HTTP 207

Rate limiting

The CLI enforces a client-side limit of 200 requests per minute by default and retries HTTP 429 responses, honoring Retry-After. The limit is per process, so account for other processes using the same instance.

For a tenant with a different limit, use --rate-limit, SEVENTHINGS_RATE_LIMIT, or save a profile setting:

seventhings config set production --profile-rate-limit 100

For endpoint schemas and API behavior, see the API Reference.