Install and Configure the quemsi CLI

Role: Developer or pipeline owner · Time: about 5 minutes

The quemsi CLI is an HTTP client for /api/v1. It is not the Quemsi agent: no Keycloak CLIENT_ID, no long-poll, no database access. Use it from a laptop, CI, or a coding agent. For console clicks, use Guides.

Before you start

You have a Quemsi company and at least one agent that is ONLINE.
You know the data name and agent name you will call.
You can open Company Setup → API tokens.

Steps

1

Download the CLI

Binaries are published at /cli-releases/latest/. Put the binary on PATH. On Windows the file is quemsi.exe; the command is still quemsi.

Linux:

curl -fsSL -o quemsi https://quemsi.com/cli-releases/latest/quemsi && chmod +x quemsi && sudo mv quemsi /usr/local/bin/quemsi

Windows: download quemsi.exe and add it to PATH.

JAR (Java 21), either OS:

curl -fsSL -o quemsi.jar https://quemsi.com/cli-releases/latest/quemsi.jar
java -jar quemsi.jar --help

Check the install:

quemsi --help
quemsi snapshot --help

2

Create an API token

Open Company Setup → API tokens. Full clicks: Create API tokens.

CI / scripts: bind to the pipeline agent; scopes depend on the job (snapshot+read, or restore+read, or all three).
Laptop / coding agent: bind to your local agent; prefer snapshot and read only (omit restore).

Copy the qsk_… secret once. Do not commit it.

3

Set environment variables

Shell profile, CI secrets, or Cursor env:

export QUEMSI_TOKEN=qsk_...
# Optional — defaults to https://quemsi.com
export QUEMSI_URL=https://quemsi.com

You can also pass --token and --url on each command. Prefer the env vars so hooks and pipelines stay simple.

4

Run a first command

--wait is the default: the CLI polls until the flow finishes. As soon as the run is scheduled it prints a console link so you can watch progress and logs:

you can watch progress at https://quemsi.com/app/flows/execution/123
waiting for snapshot execution 123

Example snapshot:

quemsi snapshot --data YOUR_DATA --agent YOUR_AGENT \
  --tag work=baseline --tag purpose=pre-schema \
  --descript "first CLI snapshot"

Example restore (overwrites the target database):

quemsi restore --agent YOUR_AGENT --target-datasource YOUR_DATASOURCE \
  --data YOUR_DATA --tag work=baseline

Exit 0 on SUCCESS; exit 1 on FAILED or SKIPPED. Open the printed URL while signed in to see steps and logs. Use --no-wait to print the execution id on stdout and exit after POST.

What next

Coding agent snapshot — Cursor rule and hook so a laptop agent snapshots before Hibernate or a migration.
Snapshot before deploy — CI recipe before a release.
Restore before tests — CI recipe for a known test state.
Jenkins integration — credentials and Declarative Pipeline stages.
API reference — raw /api/v1 if you prefer curl.

Troubleshooting

QUEMSI_TOKEN is required — set the env var or pass --token.
token-agent-mismatch — the token is bound to a different agent; use that agent’s name or create a new token.
ambiguous-flow — pass --flow with the forward flow name when more than one backup flow exists.
Agent offline — start the agent; the API will not queue work onto an offline agent.
Download 404 — the release folder may not be published yet on this host; use the JAR from the same /cli-releases/latest/ path when available.

Install and configure the quemsi CLI