@rolino/cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# @rolino/cli
+
+## 0.1.0
+
+### Minor Changes
+
+- fdc916f: Add least-privilege, idempotent project creation across the public API, SDK,
+  CLI, and local stdio MCP, including atomic paired-brand creation.
+- 2f5220f: Expose Bluesky consistently across public publishing contracts, the SDK, CLI,
+  and MCP, including 300-grapheme caption overrides, text and image readiness,
+  health reporting, scheduling, and immediate publishing. The fixed release group
+  also advances `@rolino/local-auth` even though its source does not change.
+- edd5f2e: Validate YouTube descriptions by their 5,000-byte UTF-8 provider limit so every Rolino client rejects multibyte text that YouTube would refuse.
+- 1b644ef: Prepare the first coordinated public release of Rolino's contracts, SDK, shared
+  local authentication, CLI, and local stdio MCP packages.
+- 420484d: Add reusable media discovery and direct local-file uploads across the public
+  API contracts, SDK, CLI, and MCP so agents can safely prepare folder-based
+  social scheduling workflows. The fixed release group also advances
+  `@rolino/local-auth` even though its source does not change.
+- 52373a6: Expose YouTube consistently across public contracts, the SDK, CLI, and MCP,
+  including explicit draft metadata, readiness and health, early scheduled
+  preparation, exact publish confirmation, and typed pending reconciliation.
+  The fixed release group also advances `@rolino/local-auth` even though its
+  source does not change.
+
+### Patch Changes
+
+- Updated dependencies [fdc916f]
+- Updated dependencies [2f5220f]
+- Updated dependencies [edd5f2e]
+- Updated dependencies [1b644ef]
+- Updated dependencies [420484d]
+- Updated dependencies [52373a6]
+  - @rolino/contracts@0.1.0
+  - @rolino/sdk@0.1.0
+  - @rolino/local-auth@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vlad
+
+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,192 @@
+# `@rolino/cli`
+
+The `rolino` command-line interface for people, scripts, and coding agents.
+Its stable machine mode keeps result data on stdout and diagnostics on stderr.
+Network requests go through `@rolino/sdk`, which uses the Node.js native
+`fetch` implementation; the CLI does not depend on Axios or another HTTP
+client package.
+
+## Installation
+
+The supported installation keeps the CLI independent from MCP:
+
+```bash
+npm install --global @rolino/cli
+```
+
+Users who also want local MCP will install both packages explicitly:
+
+```bash
+npm install --global @rolino/cli @rolino/mcp
+```
+
+The CLI-only installation does not include `@rolino/mcp` or the MCP SDK. If a
+CLI-only user runs `rolino setup mcp`, the command explains how to install the
+separate MCP package and then retry. Rolino never downloads or installs MCP
+silently.
+
+Initial commands:
+
+```text
+rolino auth login
+rolino auth status
+rolino auth logout
+rolino setup mcp --client codex [--scope user|project]
+rolino setup mcp --client claude-code [--scope user|project]
+rolino whoami
+rolino projects create --name NAME [--type PRODUCT|SERVICE|PERSONAL|COMPANY] [--website URL] [--description TEXT] [--idempotency-key KEY] --yes
+rolino projects list [--limit 50] [--cursor ID]
+rolino projects show PROJECT_ID
+rolino media list --project PROJECT_ID [--type IMAGE|VIDEO] [--query TEXT] [--limit 50] [--cursor ID]
+rolino media upload FILE_PATH --project PROJECT_ID --yes
+rolino posts create --project PROJECT_ID --caption TEXT [--platform INSTAGRAM|TIKTOK|YOUTUBE|BLUESKY] [--media ASSET_ID] --yes
+rolino posts update POST_ID --project PROJECT_ID --expected-version VERSION --caption TEXT [--platform INSTAGRAM|TIKTOK|YOUTUBE|BLUESKY] [--media ASSET_ID] --yes
+rolino posts list --project PROJECT_ID [--limit 50] [--cursor ID] [--status STATUS]
+rolino posts show POST_ID --project PROJECT_ID
+rolino posts readiness POST_ID --project PROJECT_ID
+rolino posts schedule preview POST_ID --project PROJECT_ID --expected-version VERSION --at ISO_DATE --timezone IANA_TIMEZONE
+rolino posts schedule execute POST_ID --project PROJECT_ID --expected-version VERSION --at ISO_DATE --timezone IANA_TIMEZONE --confirmation-token TOKEN [--idempotency-key KEY]
+rolino posts publish preview POST_ID --project PROJECT_ID --expected-version VERSION --platform INSTAGRAM|TIKTOK|YOUTUBE|BLUESKY
+rolino posts publish execute POST_ID --project PROJECT_ID --expected-version VERSION --platform INSTAGRAM|TIKTOK|YOUTUBE|BLUESKY --confirmation-token TOKEN [--idempotency-key KEY]
+rolino integrations health --project PROJECT_ID
+rolino calendar list --project PROJECT_ID [--from ISO_DATE --to ISO_DATE] [--limit 50] [--cursor CURSOR]
+rolino doctor
+```
+
+Interactive login opens the configured Rolino instance in a browser, obtains
+explicit workspace approval, and exchanges a single-use code with PKCE S256.
+The approval screen always includes identity and workspace reads and lets the
+user independently opt into project creation, draft writing, confirmed
+scheduling, and confirmed immediate publishing. Optional permissions start off,
+and existing credentials never gain a newly selected permission. Revoke and
+reauthorize an existing connection to grant project creation. The bearer
+credential never passes through a browser URL. Saved credentials are scoped by
+base URL and stored in the operating-system configuration directory;
+`ROLINO_CONFIG_DIR` overrides that location. `auth logout` revokes the calling
+credential before deleting its local copy.
+
+The terminal waits five minutes for browser approval. If that request expires,
+close the old approval page and run `rolino auth login` again; refreshing the
+page cannot restart the closed loopback listener.
+
+`setup mcp` finds the built Rolino stdio server, previews the exact token-free
+configuration, and asks before changing anything. User scope is the default.
+Codex configuration is written to `CODEX_HOME/config.toml` or
+`~/.codex/config.toml`; Claude Code user scope is applied through its official
+CLI. Project scope writes `.codex/config.toml` or `.mcp.json` in the current
+directory. Existing file-backed configuration is backed up with a
+`.rolino-backup` suffix. Use `--dry-run` to preview in scripts and `--yes` to
+provide explicit non-interactive consent; `--agent` never implies consent.
+
+Draft creation and update never schedule or publish. Both require interactive
+confirmation or `--yes`; non-interactive and agent-mode calls fail before an
+HTTP request unless `--yes` is present. Retries use `--idempotency-key` (the
+request ID by default), and updates require the current `--expected-version`
+shown by `posts show` so stale automation cannot overwrite a newer edit.
+
+Media uploads use the deployment's existing local, S3-compatible, or
+Cloudflare R2 storage. The CLI validates the local file, requests a short-lived
+signed upload, sends bytes directly to storage, and registers the reusable
+asset only after the stored size and content type match. Uploading requires
+interactive confirmation or `--yes` and never creates or schedules a post.
+
+YouTube drafts require exactly one stored video and explicit settings. Supply
+`--youtube-title`, `--youtube-category-id`, `--youtube-privacy`, and
+`--youtube-made-for-kids yes|no`; repeat `--youtube-tag` as needed. Optional
+flags include `--youtube-caption`, `--youtube-synthetic-media`, and
+`--no-youtube-notify-subscribers`. The YouTube caption override is the video
+description; otherwise Rolino uses the shared caption. For example:
+
+```text
+rolino posts create --project PROJECT_ID --caption "Launch description" --platform YOUTUBE --media VIDEO_ASSET_ID --youtube-title "Launch video" --youtube-category-id 22 --youtube-privacy PRIVATE --youtube-made-for-kids no --youtube-tag launch --yes
+```
+
+Google may restrict uploads from unaudited API projects to Private. Rolino does
+not infer audit approval from configuration. A scheduled YouTube post must
+target Public; confirmed scheduling starts its private resumable upload
+immediately so processing can finish before the target time.
+
+Bluesky drafts can be text-only or include up to four stored JPEG, PNG, or WebP
+images. Use `--bluesky-caption` for a destination-specific override of up to
+300 graphemes:
+
+```text
+rolino posts create --project PROJECT_ID --caption "Shared launch" --platform BLUESKY --bluesky-caption "Launch day 🦋" --yes
+```
+
+Project creation also requires interactive confirmation or `--yes`. It
+atomically saves a project and its paired brand, but does not start research,
+connect accounts, schedule posts, or publish. A fresh CLI invocation generates
+a fresh request ID and therefore a fresh default idempotency key. To retry the
+same logical creation across invocations, pass the original request ID or an
+explicit stable value through `--idempotency-key`.
+
+Scheduling is intentionally two-step. `posts schedule preview` validates the
+exact time, timezone, current post version, readiness, and live provider health,
+then returns a five-minute one-time confirmation. `posts schedule execute`
+must repeat the same values and adds an idempotency key; the server rechecks
+everything before atomically consuming the confirmation and scheduling. For
+scripts, prefer `ROLINO_CONFIRMATION_TOKEN` over placing the short-lived token
+in process arguments. Neither `--agent` nor any client-side flag bypasses the
+server confirmation.
+
+When YouTube is selected, the preview states whether confirmed execution starts
+or resumes early private preparation. A schedule execution may return
+`PENDING` while YouTube confirms a remote schedule change; that result is not a
+published state, and the same idempotency key is safe to replay.
+
+Immediate publishing uses the same server-enforced pattern. `posts publish
+preview` validates the current version, exact destination set, readiness, live
+provider health, and retry safety without publishing. `posts publish execute`
+must repeat those values with the one-time confirmation and an idempotency key.
+A successful execute durably queues the selected destinations for immediate
+delivery; Rolino's worker performs provider calls and reconciles ambiguous
+network results so an unsafe retry cannot duplicate a post. Use
+`ROLINO_CONFIRMATION_TOKEN` for scripts instead of putting the token in process
+arguments. YouTube remains `PREPARING` while its resumable upload and provider
+processing are incomplete; only provider-confirmed visibility becomes
+published.
+
+The CLI cannot enable YouTube or Bluesky, or infer Google/YouTube approval.
+Those are server-side deployment controls. Self-hosted operators should
+complete the
+[YouTube operations guide](https://github.com/deifos/rolino/blob/main/docs/integrations/youtube.md)
+and
+[Bluesky operations guide](https://github.com/deifos/rolino/blob/main/docs/integrations/bluesky.md)
+before live testing.
+
+Configuration is read from `ROLINO_URL`, `ROLINO_TOKEN`, `ROLINO_CONFIG_DIR`,
+`ROLINO_OUTPUT`, `ROLINO_TIMEOUT`, and the short-lived
+`ROLINO_CONFIRMATION_TOKEN`, with non-secret command options for base
+URL, output, timeout, and request correlation. `ROLINO_TOKEN` takes precedence
+over saved credentials. Piped stdout defaults to JSON; `--agent` adds stable
+next-command suggestions. Timeouts accept integer milliseconds or values such
+as `500ms`, `15s`, and `1m`.
+
+Stable exit codes:
+
+| Code | Meaning |
+| ---: | --- |
+| 0 | Success |
+| 1 | Unexpected CLI failure |
+| 2 | Usage/configuration error |
+| 3 | Authentication required or expired |
+| 4 | Permission or scope denied |
+| 5 | Resource unavailable or not found |
+| 6 | Conflict or stale version |
+| 7 | Validation failure |
+| 8 | Rate limited |
+| 9 | Rolino server failure |
+| 10 | Network failure |
+| 11 | Timeout |
+| 12 | User cancelled |
+
+## Support, security, and license
+
+Stable releases are published only after the maintainer approves the release
+gate. Report bugs through the
+[Rolino issue tracker](https://github.com/deifos/rolino/issues) and security
+issues through the repository's
+[security policy](https://github.com/deifos/rolino/security/policy).
+
+`@rolino/cli` is available under the MIT License.