@shuffl/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shuffl LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# 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.
+
+```sh
+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`](https://www.npmjs.com/package/@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", "units.save"]`. The issuer must hold `credentials.api.create` and every requested permission. See [endpoint permissions](https://shuffl-rebuild.vercel.app/docs/api-permissions).
+
+## Authentication and commands
+
+Create an API key in **Settings → API keys**, choosing only the endpoint permissions you need, then feed it through stdin:
+
+```sh
+# Your credential manager supplies the token on stdin.
+credential-command | shuffl login --base-url https://YOUR-SHUFFL-HOST --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_TOKEN` 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.
+
+Select the workspace when creating the token. Each token controls exactly that workspace; switching workspaces requires a token issued there. There is no workspace flag that can broaden the token's authority. `shuffl workspaces current --json` reads back the selected workspace. `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](https://shuffl-rebuild.vercel.app/docs/sdk):
+
+```sh
+shuffl units list --json
+shuffl units save --input-file team-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.
+
+Full guide: [Use the Shuffl CLI](https://shuffl-rebuild.vercel.app/docs/cli).

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from './index.js';
+process.exitCode = await runCli(process.argv.slice(2));

package/dist/commands.generated.d.ts

@@ -0,0 +1,2 @@
+import type { CommandDefinition } from './types.ts';
+export declare const commands: CommandDefinition[];