# Use the Shuffl CLI

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

Audience: Developers and automation owners

Kind: How-to guide

Canonical: https://shuffl.ai/docs/cli

<a id="install"></a>
## 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.

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

- [@shuffl/cli on npm](https://www.npmjs.com/package/@shuffl/cli)

- [Install the SDK instead](https://shuffl.ai/docs/sdk#install)

<a id="login"></a>
## 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.

```sh
# 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
```

- [Open API keys](https://shuffl.ai/app/settings/api-keys)

- [Endpoint permission reference](https://shuffl.ai/docs/api-permissions)

<a id="read"></a>
## 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.

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

- [Evidence and pagination behavior](https://shuffl.ai/docs/sdk#read)

<a id="writes"></a>
## 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.

- [Department command and retry example](https://shuffl.ai/docs/sdk#writes)

- [Endpoint permission reference](https://shuffl.ai/docs/api-permissions)

<a id="company"></a>
## 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.

```sh
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
```

- [Company settings API reference](https://shuffl.ai/docs/api-reference/company)

- [Company keys and their grants](https://shuffl.ai/docs/api-permissions#company-keys)

<a id="errors"></a>
## 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.

- [Recover from an API error](https://shuffl.ai/docs/sdk#errors)

- [Error codes](https://shuffl.ai/docs/api-reference#errors)

- [Open API keys](https://shuffl.ai/app/settings/api-keys)

## Related guides

- [Use the SDK and HTTP API](https://shuffl.ai/docs/sdk)

- [SDK and CLI recipes](https://shuffl.ai/docs/sdk-cookbook)

- [API endpoint permissions](https://shuffl.ai/docs/api-permissions)

- [Use Shuffl with your agent](https://shuffl.ai/docs/agent-quick-start)

Agent documentation index: https://shuffl.ai/llms.txt