Use the Shuffl CLI
Run Shuffl operations from scripts without a model, with JSON output and the same endpoint permissions as the SDK.
Developers and automation owners
Read as MarkdownAll guides as textAgent documentation index
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 ships with the SDK under the same version, so shuffl --version tells you which API contract it uses. To pin it in a project, add @shuffl/cli as a dev dependency and run npx shuffl.
npm install --global @shuffl/cli
shuffl --version
shuffl --help
# Or run it once without installing:
npx @shuffl/cli --helpConnect a workspace key
Ask an administrator for an API key from Manage → Settings → API keys, or create one there yourself. Pass SHUFFL_TOKEN and SHUFFL_BASE_URL through the environment from your credential manager, or pipe the secret into login --token-stdin. SHUFFL_TOKEN in the environment wins over a saved login, and --base-url on any command overrides the saved URL. Never put the secret in a command-line argument. Login checks the key before saving it.
A token belongs to one workspace, and no workspace flag can widen it. Create a separate key in each workspace you need. Saved credentials only work with the base URL they were saved for.
Local configuration is saved with mode 0600 at $XDG_CONFIG_HOME/shuffl/config.json (default ~/.config/shuffl/config.json); SHUFFL_CONFIG_DIR overrides that directory. Logout removes the saved local copy. Revoke the key in Settings to invalidate other copies.
# credential-command represents your credential manager; replace it.
credential-command | shuffl login --base-url https://shuffl-rebuild.vercel.app --token-stdin
shuffl teams current --json
shuffl permissions list --jsonRead supported capabilities
Select knowledge.search for the knowledge example, and users.list only if you want directory access. Each command’s help names its permission and whether it reads or writes. Help works without credentials.
shuffl knowledge search --help
shuffl knowledge search --query "vacation policy" --json
shuffl users list --limit 25 --jsonSupply explicit command input
Every operation accepts --input JSON, --input - for stdin, or --input-file FILE. Top-level properties become flags; nested arrays and objects are JSON. Use one input form per call. For a management write, put the full command and a stable request key in a file, check it, then send it once.
For example, shuffl units save --input-file team-command.json --json uses the same command fields and receipt behavior as units.save in the SDK guide. Grant units.save separately from units.list and commands.get. Sensitive writes also need the confirm value. Commands only call Shuffl; they don’t start a model.
Handle output, errors and logout
--json writes one JSON value to stdout, including {error: {code, message}} on failure. Exit codes are 0 success, 1 service failure, 2 usage/validation and 3 authentication/authorization. Human-readable errors go to stderr. Repeated flags and ambiguous input are rejected.
If a call is denied, check permissions and the current workspace and role. After a network failure or interrupted write, check the receipt before creating a new command. Don’t print newly created one-time credentials into shared logs.
Run shuffl logout to remove the stored credential, then revoke the key in Settings when access should end. Remove tokens you supplied through the environment from your credential manager or environment too.