Shuffl CLI

Every public Shuffl API operation as a scriptable command with JSON output. Commands do not start a model or agent.

Installation

Requires Node.js 22 or later.

npm install --global @shuffl/cli
shuffl --version
shuffl --help

Or run it without installing: npx @shuffl/cli --help. To pin it in a project, add @shuffl/cli as a dev dependency and run npx shuffl. The CLI is built on @shuffl/sdk and released with it under one version; its operation names, help and input flags are generated from the public API contract.

shuffl permissions list --json discovers endpoint grants. Each command’s --help shows its permission ID and Read/Write classification. Create a delegated key with shuffl credentials api create --input-file key-command.json --json, using a permissions array such as ["users.list", "groups.save"]. The issuer must hold credentials.api.create and every requested permission. See endpoint permissions.

Authentication and commands

Create an API key in Settings → API keys, choosing only the endpoint permissions you need, then feed it through stdin:

# Your credential manager supplies the token on stdin.
credential-command | shuffl login --base-url https://shuffl.ai --token-stdin

shuffl users list --limit 25 --json
shuffl programs list --json
shuffl programs preview --id PROGRAM_ID --seed preview-2026-09 --json
shuffl programs pause --id PROGRAM_ID --json
shuffl programs create --input-file create-program.json --json
shuffl programs update --input-file update-program.json --json
shuffl logout

Alternatively set SHUFFL_API_KEY and SHUFFL_BASE_URL through your environment. Tokens are never accepted as command-line arguments or printed after login. Saved credentials are stored with mode 0600 under $XDG_CONFIG_HOME/shuffl/config.json (default ~/.config/shuffl/config.json). SHUFFL_CONFIG_DIR overrides the Shuffl directory. Logout removes the local copy; revoke the token in Settings to disable other copies.

The saved token cannot be used with a different --base-url; log into that server or supply an explicit environment token. Login verifies the token before saving it. For production, use https://shuffl.ai. If your saved login uses the old Vercel host, log in again with the canonical URL; environment-based setups must update SHUFFL_BASE_URL.

Select the team when creating the token. Each token controls exactly that team; switching teams requires a token issued there. There is no team flag that can broaden the token's authority. shuffl teams current --json reads back the selected team. users list accepts --limit (1–100) and --cursor from the previous response's nextCursor; other resources retain the pagination fields shown by their command help.

Every operation accepts --input JSON, --input - for stdin, or --input-file FILE. Top-level schema properties also become flags, such as --id, --limit, and --expected-revision. Boolean values are true or false; nested objects and arrays are JSON. --help requires no credentials. Repeated flags and ambiguous inputs are rejected.

--json writes one JSON value to stdout, including { "error": { "code", "message" } } on failure. Exit codes: 0 success, 1 service failure, 2 usage/validation, 3 authentication/authorization. Human output uses formatted JSON and errors on stderr. Commands do not start a model or agent.

Programs are created paused by default. Keep the same requestKey for a retry, and use expectedRevision to update the version you reviewed. Activating a program enables its schedule. A requested run is queued durably and can be inspected with shuffl runs get --id RUN_ID.

Management resources use the same nested command names as the SDK:

shuffl groups list --json
shuffl groups save --input-file group-command.json --json
shuffl commands get --id RECEIPT_ID --json
shuffl knowledge sources import-pdf --input-file pdf-command.json --json

Management writes require requestKey and return {receipt, result}. Sensitive writes also require confirm equal to the SDK operation name. Keep the same input/key on retry: the duplicate returns only the receipt and result: null, without repeating the write or disclosing an old result. Read current resources to reconcile an unknown outcome.

Company settings

Commands under shuffl company take a company key (shuffl_company_) from Company settings → API keys instead of a workspace key:

credential-command | shuffl login --company --base-url https://shuffl.ai --token-stdin
shuffl company current --json
shuffl company members list --limit 100 --json
shuffl company members remove --user-id USER_ID --json
shuffl logout --company

Or set SHUFFL_COMPANY_KEY and SHUFFL_BASE_URL. The company key is saved in company.json next to config.json, and only shuffl company commands send it; shuffl logout --company removes it. Each command's --help names its company permission. See company keys.

Full guide: Use the Shuffl CLI.

License

MIT © Shuffl LLC. See LICENSE.