CLI

The Limitry command-line interface (CLI) sets up your limits and checks them from a terminal or a script: create a limit, try a check, and see who is using what. It acts as you, in the workspaces you allow.

Install

npm install -g @limitry/cli

limitry login

Your browser opens. Sign in, choose which workspaces the CLI may use and what it may do, and click Allow. The CLI creates a personal access token for this computer, valid for 90 days and listed under Account → API tokens, and stores it in ~/.config/limitry/.

On a server or in CI there’s no browser, so pass a token instead. Set it in the environment and the CLI writes nothing to disk; login --token saves it like a browser sign-in. A workspace API key works too: it acts in its own workspace, so there’s no workspace to choose.

LIMITRY_TOKEN=pat_… limitry whoami           # a personal access token
LIMITRY_TOKEN=lim_test_… limitry limits list   # a workspace API key
limitry login --token "$TOKEN"   # or save it (or: echo "$TOKEN" | limitry login)

limitry logout revokes the token and forgets it.

Common tasks

Create a limit, in test:

limitry limits create --name "AI replies per day" --subject '{"kind":"user"}' \
  --action ai-call --amount 100 --window day

Check a user, as your code would:

limitry check user:usr_123 ai-call

See where a user stands, without counting anything:

limitry usage standing --subject user:usr_123

See who is using a limit now, and its usage over time:

limitry usage subjects --limit-id lmt_123
limitry usage query --limit-id lmt_123 --granularity day

When a limit is right, copy it to live from the Limits page in the app, or create it with --environment live.

Choose a workspace

limitry workspace list
limitry workspace use acme       # the default for later commands
limitry workspace audit-events list --workspace other-co   # one call elsewhere

Test and live

Commands act in test unless you say otherwise, so a mistake changes test limits, never the ones your customers depend on. To act in live, name it for one command, for a shell, or as the default:

limitry limits list --environment live      # one command
export LIMITRY_ENVIRONMENT=live             # this shell
limitry environment use live                # the default from now on
limitry environment                         # which one, and where it came from
limitry environment unset                   # back to test

--environment wins over LIMITRY_ENVIRONMENT, which wins over the default you set. After every command that calls the API, it prints Environment: test or Environment: live on stderr, so you always know which side it changed. Stdout stays the command’s output. With --json, an error’s JSON carries environment too. See Test and live.

Commands

Commands sit in groups, one for each thing they work on:

limitry limits list
limitry limits create --name "AI replies per day" --subject '{"kind":"user"}' \
  --action ai-call --amount 100 --window day
limitry checks create --subject '{"kind":"user","id":"usr_123"}' \
  --action ai-call
limitry limits archive lmt_123

Two everyday commands have shortcuts. Each sends the same request as its long form:

Shortcut	Long form
`limitry check <kind>:<id> <action>`	`limitry checks create --subject '{…}' --action <action>`
`limitry sync [file]`	`limitry limits sync [file]`

limitry check takes --cost and --shared <kind>:<id> (repeat it for each shared subject) and prints one line: allowed or refused, what is left, and when it resets. A refusal is an answer, so it exits 0. For a reservation (--mode reserve), use limitry checks create. limitry sync keeps your limits in a file: see Sync limits from GitHub.

limitry --help lists the groups, limitry limits --help a group’s commands, and --help on a command its options.
Lists print one page. The last line gives the --cursor for the next.
A command that can’t be undone asks for --yes.

Every command:

General

Command	What it does
`limitry login`	Sign in through the browser (or store a personal access token with --token)
`limitry logout`	Revoke the stored token and forget it
`limitry whoami`	Who the token acts as, and their workspaces
`limitry config`	Show the effective settings (token masked)
`limitry sync [file]`	Short for `limitry limits sync`
`limitry check <subject> <action>`	Short for `limitry checks create`
`limitry api <method> <path>`	Call any endpoint as the selected workspace (escape hatch)

Checks

Command	What it does
`limitry checks create`	Check whether a subject may act

Limits

Command	What it does
`limitry limits archive <limit-id>`	Archive a limit
`limitry limits create`	Create a limit
`limitry limits credits create <limit-id>`	Add credits to a balance
`limitry limits credits list <limit-id>`	List a balance's credits
`limitry limits get <limit-id>`	Get a limit
`limitry limits list`	List limits
`limitry limits restore <limit-id>`	Restore an archived limit
`limitry limits sync [file]`	Make your limits match a file (shortcut: limitry sync)
`limitry limits update <limit-id>`	Change a limit

Usage

Command	What it does
`limitry usage query`	Get a limit's usage over time
`limitry usage standing`	Get where a subject stands
`limitry usage subjects`	List who is using a limit now

Subjects

Command	What it does
`limitry subjects get <subject-kind> <subject-id>`	Get a subject
`limitry subjects reset <subject-kind> <subject-id>`	Reset a subject's limits
`limitry subjects update <subject-kind> <subject-id>`	Set a subject's billing date

Reservations

Command	What it does
`limitry reservations commit <reservation-id>`	Commit a reservation
`limitry reservations extend <reservation-id>`	Extend a reservation
`limitry reservations release <reservation-id>`	Release a reservation

Environment

Command	What it does
`limitry environment list`	Show the environment commands act in
`limitry environment use <name>`	Make <name> the default environment for commands
`limitry environment unset`	Forget the default environment (the product's default applies)

Workspace and team

Command	What it does
`limitry workspace list`	List the workspaces the token can act in
`limitry workspace use <slug>`	Make <slug> the default workspace for workspace commands
`limitry workspace approval-actions list`	List the actions you can ask approval for
`limitry workspace approval-requests create`	Ask a person to approve an action
`limitry workspace approval-requests get <request-id>`	Check an approval request
`limitry workspace approval-requests redeem <request-id>`	Collect an approved secret once, into an env file (never printed)
`limitry workspace audit-events list`	List workspace audit events
`limitry workspace event-types list`	List event types
`limitry workspace get`	Get the current workspace
`limitry workspace invitations list`	List pending invitations
`limitry workspace members list`	List workspace members
`limitry workspace teams list`	List teams
`limitry workspace usage`	Get your plan's usage this period
`limitry workspace webhook-deliveries list <endpoint-id>`	List an endpoint's deliveries
`limitry workspace webhook-deliveries redeliver <endpoint-id> <delivery-id>`	Redeliver an event
`limitry workspace webhook-endpoints create`	Add a webhook endpoint
`limitry workspace webhook-endpoints delete <endpoint-id>`	Remove a webhook endpoint
`limitry workspace webhook-endpoints enable <endpoint-id>`	Re-enable a webhook endpoint
`limitry workspace webhook-endpoints get <endpoint-id>`	Get a webhook endpoint
`limitry workspace webhook-endpoints list`	List webhook endpoints
`limitry workspace webhook-endpoints test <endpoint-id>`	Send a test event

Personal access tokens

Command	What it does
`limitry user me`	Get the current user
`limitry user revoke-token`	Revoke the token making this request

Scripts and agents

Add --json to any command to get the API’s exact JSON on stdout. Errors then go to stderr as JSON too, in the API’s error envelope with the HTTP status:

limitry limits list --json | jq '.items[].name'

{
  "error": {
    "code": "forbidden",
    "message": "…",
    "status": 403,
    "requestId": "…"
  }
}

The exit code is 0 on success and 1 on any failure, including a refused API call or a missing flag.

The API underneath

For developers: every command calls the public API, the same one your code uses, with your personal access token.

A command that calls one API operation links to it in the list above. Under Endpoints, each operation shows its command next to the same call in TypeScript, Python and curl.
Ids in an operation’s path are the command’s arguments, and its other inputs are flags. --data '{…}' sends a whole JSON body.
Every write sends an idempotency key, and a failed attempt is retried with the same key. To run a command again without repeating its writes, pass the same --idempotency-key <key> both times.
limitry api <method> <path> calls any endpoint directly.