CLI documentation · Slimlytics

Why the command is slimlytics, not slim: SlimToolkit already owns the popular slim command and has more than 23,000 GitHub stars. Avoiding that collision keeps installs predictable.

Install

Cargo builds the pinned cli-v0.2.0 release tag straight from GitHub with a locked release build. Requirements: a recent stable Rust toolchain with Cargo.

cargo install --locked \
  --git https://github.com/djedi/slimlytics --tag cli-v0.2.0 slimlytics-cli

slimlytics --version
slimlytics --help

Install from a local checkout instead:

cargo install --locked --path cli

Cargo places the executable in ${CARGO_HOME:-$HOME/.cargo}/bin. Ensure that directory is on PATH.

Authenticate

Interactive login exchanges your password for a short-lived session and then creates a durable, revocable personal API token:

slimlytics auth login --email you@example.com
slimlytics auth status

For automation, keep passwords and tokens out of process arguments:

printf '%s\n' "$SLIMLYTICS_PASSWORD" | \
  slimlytics auth login --email you@example.com --password-stdin

printf '%s\n' "$SLIMLYTICS_TOKEN" | \
  slimlytics auth use-token --token-stdin

Revoke the active personal token while signing out:

slimlytics auth logout --revoke

Complete command reference

Global options can appear before or after the command: --json emits machine-readable output and --api-url URL selects a self-hosted API.

slimlytics auth login --email EMAIL [--password-stdin] [--token-name NAME] [--expires-in-days DAYS]

Sign in and create a durable personal API token.

The password obtains a short-lived session JWT. The CLI exchanges it for a personal API token, stores only that token, and never saves the password.

--password-stdin reads the password without exposing it in process arguments.
--token-name defaults to slimlytics-cli.
--expires-in-days accepts 1–3650 and defaults to 365.

slimlytics auth use-token [--token-stdin]

Import an existing personal API token.

Reads a slyt_ token from piped standard input, verifies it against the account endpoint, then stores it securely. It does not prompt or accept the token as a process argument; --token-stdin is required when invoking it from a terminal.

slimlytics auth status

Verify the saved credential and show the current account.

Returns a nonzero status when the token is absent, expired, revoked, or rejected.

slimlytics auth logout [--revoke]

Remove local authentication.

With --revoke, the exact personal token authenticating the request is revoked before the local credential file is removed.

slimlytics account show

Show the authenticated account.

Human output shows email and account ID. --json also returns the creation timestamp. Accepts either a saved token or SLIMLYTICS_TOKEN.

slimlytics token list

List active personal API tokens.

Human output shows IDs, names, and non-secret prefixes. --json also returns creation, expiration, and last-use timestamps. Token secrets are never listed.

slimlytics token revoke TOKEN_UUID

Immediately revoke a personal API token.

Revocation is account-scoped and takes effect on the next request.

slimlytics site list

List all sites in the account.

JSON output returns the complete persisted site settings.

slimlytics site show SITE

Show one site by UUID or exact domain.

A UUID is recommended for scripts. Ambiguous selectors fail rather than choosing silently.

slimlytics site add DOMAIN [--name NAME] [--timezone TZ] [--retention-days DAYS] [--origin URL]... [--server SERVER]

Create a site and return its tracking setup.

SERVER is caddy, nginx, or apache. Repeat --origin to authorize multiple browser origins.

slimlytics site ensure DOMAIN [--name NAME] [--timezone TZ] [--retention-days DAYS] [--origin URL]... [--server SERVER]

Atomically create or reuse a canonical domain.

This is the preferred idempotent operation for agents. It always returns the site, tracking snippet, server configuration, test URLs, and ordered installation steps.

slimlytics site delete SITE --yes

Delete a site and its analytics data.

The explicit --yes flag prevents accidental interactive or agent deletion.

slimlytics tracking show SITE

Generate the current first-party tracking setup.

Returns hardened reverse-proxy configuration, the minimal script tag, and script/beacon verification URLs.

slimlytics tracking configure SITE --server SERVER [--js-path PATH] [--beacon-path PATH]

Persist and render first-party tracking settings.

Paths must be same-origin single-segment paths; the JavaScript path must end in .js and must differ from the beacon path.

AI agents and JSON output

site ensure is the primary agent workflow. The server performs the ensure transaction atomically, so retries cannot create duplicate domains.

slimlytics --json site ensure example.com --server caddy

The versioned response envelope includes schemaVersion, ok, whether the site was created, all site settings, reverse-proxy configuration, the script snippet, verification URLs, and ordered steps.

json

{
  "schemaVersion": 1,
  "ok": true,
  "data": {
    "created": true,
    "site": { "id": "…", "domain": "example.com" },
    "tracking": {
      "serverConfig": "…",
      "snippet": "<script async src=\"/…js\"><\/script>",
      "scriptTestUrl": "https://example.com/…js",
      "beaconTestUrl": "https://example.com/…"
    }
  }
}

Successful JSON goes to stdout. Errors go to stderr and return a nonzero exit status. Login, status, and listings never print password or token secrets.

Configuration and environment

Name	Purpose
`SLIMLYTICS_API_URL`	API base URL. Defaults to `https://slimlytics.com`. Remote URLs must use HTTPS; HTTP is accepted only for loopback development.
`SLIMLYTICS_TOKEN`	Use a personal API token directly instead of the saved credential file.
`SLIMLYTICS_CLI_REF`	Installer source tag override. The standard installer pins `cli-v0.2.0`.
`CARGO_HOME`	Controls Cargo's install directory.

The credential file is stored in the platform configuration directory—for example, ~/Library/Application Support/slimlytics/auth.json on macOS or ~/.config/slimlytics/auth.json on Linux.

Security guarantees

Protected transport

Remote APIs require HTTPS and the HTTP client refuses all redirects, preventing credentials from following downgrade or cross-origin responses.

Private local storage

Credential directories use mode 0700 and files mode 0600 on Unix. Writes are atomic and refuse symbolic-link targets.

Revocable tokens

Personal tokens are random, hashed at rest, expire, and can be revoked individually. Plaintext is returned only at creation.

The CLI generates configuration but deliberately does not SSH into unrelated servers, reload web servers, or modify website templates. The calling human or agent retains those privileges and rollback responsibilities.

Need raw HTTP details? Open the interactive API reference or download OpenAPI JSON.