Skip to content
shuffl
Get started

Searches the public product guides only. Nothing from a workspace is read, and questions are not saved.

How-to guide

Use the Shuffl CLI

Run Shuffl operations from scripts without a model, with JSON output and the same endpoint permissions as the SDK.

For Developers and automation owners

On this page

App links open your signed-in workspace. Check the selected workspace before making changes.

Install the CLI

The CLI needs Node.js 22 or later and installs a shuffl command. It shares the SDK’s version, so shuffl --version names the API contract.

To pin it, add @shuffl/cli as a dev dependency and run npx shuffl.

Shell
npm install --global @shuffl/cli
shuffl --version
shuffl --help
# Or run it once without installing:
npx @shuffl/cli --help

Connect a workspace key

An administrator creates the API key in Workspace settings → API keys. Pass SHUFFL_API_KEY and SHUFFL_BASE_URL through the environment, or pipe the secret into login --token-stdin. Never put it in an argument.

Login checks the key before saving it.

How the CLI keeps credentials

  • SHUFFL_API_KEY wins over a saved login, and --base-url overrides the saved URL.
  • A token works in one workspace only, so create a key in each workspace you need.
  • Saved credentials work only with the base URL they were saved for.
  • The config is saved with mode 0600 at $XDG_CONFIG_HOME/shuffl/config.json (default ~/.config/shuffl/config.json). SHUFFL_CONFIG_DIR overrides the directory.
  • Logout removes the local copy. Revoke the key in Settings to stop other copies.
Shell
# credential-command represents your credential manager; replace it.
credential-command | shuffl login --base-url https://shuffl.ai --token-stdin
shuffl teams current --json
shuffl permissions list --json

Read supported capabilities

Grant knowledge.search for the knowledge example, and users.list only for directory access.

Each command’s help needs no credentials. It names the command’s permission and whether it reads or writes.

Shell
shuffl knowledge search --help
shuffl knowledge search --query "vacation policy" --json
shuffl users list --limit 25 --json

Supply explicit command input

For a management write, put the full command and a stable request key in a file, check it, then send it once.

shuffl groups save --input-file department-command.json --json behaves like groups.save in the SDK guide. Grant groups.save separately from units.list and commands.get.

Sensitive writes need the confirm value. Commands never start a model.

Ways to pass input

  • --input JSON, --input - for stdin, or --input-file FILE, one form per call.
  • Top-level properties become flags. Nested arrays and objects are JSON.

Manage company settings

shuffl company commands use a company key (shuffl_company_) from Settings → API keys and webhooks → Company keys. Pipe it into shuffl login --company --token-stdin, or set SHUFFL_COMPANY_KEY with SHUFFL_BASE_URL.

It is saved apart from the workspace key, in company.json next to config.json. Only shuffl company commands send it.

shuffl company current shows the key’s company and grants. Every other command names its grant in --help. shuffl logout --company removes the saved key; revoke it under Company keys to stop other copies.

Shell
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

Handle output, errors and logout

--json writes one JSON value to stdout, including {error: {code, message}} on failure. Human-readable errors go to stderr. Repeated flags and ambiguous input are rejected.

If a call is denied, check permissions, workspace and role. After a network failure or interrupted write, check the receipt before sending a new command.

shuffl logout removes the stored credential. When access should end, revoke the key in Settings and clear any token you supplied through the environment. Keep one-time credentials out of shared logs.

Exit codes

  • 0: success.
  • 1: service failure.
  • 2: usage or validation.
  • 3: authentication or authorization.

Was this guide helpful?