maeve-cli 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LILY DIA PTY LTD
+
+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,547 @@
+# Maeve CLI
+
+A command-line tool for the Maeve public API. Schedule posts, manage media, run analytics, and send client reviews from a terminal or a script.
+
+[![npm](https://img.shields.io/npm/v/maeve-cli.svg)](https://www.npmjs.com/package/maeve-cli)
+[![node](https://img.shields.io/node/v/maeve-cli.svg)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/maeve-cli.svg)](./LICENSE)
+
+## Install
+
+Run without installing:
+
+```bash
+npx maeve-cli auth:status
+pnpm dlx maeve-cli auth:status
+```
+
+Install globally:
+
+```bash
+npm install -g maeve-cli
+maeve auth:status
+```
+
+Or with pnpm:
+
+```bash
+pnpm add -g maeve-cli
+maeve auth:status
+```
+
+Node 22 or newer is required.
+
+## Quick start
+
+```bash
+maeve auth:login
+maeve workspaces:list
+maeve integrations:list --workspace <id>
+```
+
+## Authentication
+
+There are two ways to sign in. Pick one.
+
+### API key (for CI, servers, scripts)
+
+```bash
+export MAEVE_API_KEY="ezb_live_..."
+export MAEVE_API_URL="https://api.maevesocial.com"
+```
+
+PowerShell:
+
+```powershell
+$env:MAEVE_API_KEY="ezb_live_..."
+$env:MAEVE_API_URL="https://api.maevesocial.com"
+```
+
+Prefer the env var over `--api-key`. Flags can leak into shell history and process lists.
+
+For scoped keys stored under a named environment variable, pass the variable name instead of the secret value:
+
+```bash
+maeve --api-key-env MAEVE_API_KEY_LILY_DIA_JEWELLERY_DEMO_KEY auth:status
+maeve --api-key-env MAEVE_API_KEY_LILY_DIA_JEWELLERY_DEMO_KEY media:labels:list --workspace <id>
+```
+
+When `--api-key-env` is provided, that named variable must exist; the CLI will not silently fall back to `MAEVE_API_KEY`.
+
+### Browser login (for humans on a laptop)
+
+```bash
+maeve auth:login      # opens a browser, prints a short code
+maeve auth:whoami     # shows the signed-in user and workspaces
+maeve auth:logout     # revokes the local token
+```
+
+`auth:login` stores a revocable `ezb_cli_...` token for the API URL. Tokens expire after 7 days. They are never permanent API keys.
+
+Use `--no-browser` if you want the URL printed instead of opened.
+
+### Credential precedence
+
+The CLI uses the first credential it finds:
+
+1. `--api-key`
+2. `--api-key-env <name>`
+3. `MAEVE_API_KEY`
+4. Stored CLI login token
+
+### Where the token is stored
+
+| Platform | Path                                                |
+| -------- | --------------------------------------------------- |
+| Windows  | `%APPDATA%\Maeve\cli-auth.json`                     |
+| macOS    | `~/Library/Application Support/Maeve/cli-auth.json` |
+| Linux    | `${XDG_CONFIG_HOME:-~/.config}/maeve/cli-auth.json` |
+
+The file holds one credential per API URL. Token values are never printed by `auth:status` or any other command.
+
+## Output
+
+Successful commands write JSON to stdout. Errors write structured JSON to stderr and exit non-zero. Pipe to `jq`:
+
+```bash
+maeve workspaces:list | jq -r '.data[].id'
+maeve content:list --workspace "$WORKSPACE_ID" --status scheduled | jq '.data | length'
+```
+
+## Commands
+
+### Auth
+
+```bash
+maeve auth:status
+maeve auth:login
+maeve auth:logout
+maeve auth:whoami
+```
+
+### Workspaces
+
+```bash
+maeve workspaces:list
+```
+
+### Integrations
+
+`integrations:capabilities` returns safe publishing metadata for a connected account: post types, media types, setting field names, dynamic option keys, and capability flags. It does not expose tokens, scopes, or raw provider payloads. Use `integrations:options` with a key from that response to fetch read-only provider data such as Pinterest boards or YouTube categories.
+
+```bash
+maeve integrations:list --workspace <id>
+maeve integrations:capabilities --workspace <id> --integration <id>
+maeve integrations:options --workspace <id> --integration <id> --key pinterest-boards
+maeve integrations:options --workspace <id> --integration <id> --key youtube-video-categories --json options.json
+```
+
+Example option body:
+
+```json
+{ "regionCode": "AU" }
+```
+
+### Media
+
+```bash
+maeve media:list --workspace <id>
+maeve media:list --workspace <id> --type image --label-ids <id,id> --favorite
+maeve media:list --workspace <id> --state deleted
+maeve media:upload ./image.png --workspace <id>
+maeve media:get --workspace <id> --id <mediaId>
+maeve media:update --workspace <id> --id <mediaId> --json media-update.json
+maeve media:download-url --workspace <id> --id <mediaId>
+maeve media:view-url --workspace <id> --id <mediaId>
+maeve media:archive --workspace <id> --id <mediaId>
+maeve media:delete --workspace <id> --id <mediaId>
+```
+
+`media:delete` and `media:bulk-delete` move active media to the Bin. The API returns `deleteAfter`; media attached to scheduled posts is blocked with `MEDIA_ATTACHED_TO_SCHEDULED_POST`.
+
+Folders and labels:
+
+```bash
+maeve media:folders:list --workspace <id> --parent-id root
+maeve media:folders:get --workspace <id> --id <folderId>
+maeve media:folders:path --workspace <id> --id <folderId>
+maeve media:folders:create --workspace <id> --json media-folder.json
+maeve media:folders:update --workspace <id> --id <folderId> --json media-folder.json
+maeve media:folders:move --workspace <id> --id <folderId> --json media-folder-move.json
+maeve media:folders:delete --workspace <id> --id <folderId>
+maeve media:labels:list --workspace <id> --search approved
+maeve media:labels:create --workspace <id> --json media-label.json
+maeve media:labels:update --workspace <id> --id <labelId> --json media-label.json
+maeve media:labels:delete --workspace <id> --id <labelId>
+maeve media:labels:attach --workspace <id> --id <mediaId> --json media-label-ids.json
+maeve media:labels:detach --workspace <id> --id <mediaId> --json media-label-ids.json
+```
+
+`media:labels:*` is the canonical Media Room organization command family. If a global install still shows `media:tags:*`, upgrade `maeve-cli`.
+
+Bulk operations:
+
+```bash
+maeve media:bulk-archive --workspace <id> --json media-ids.json
+maeve media:bulk-move --workspace <id> --json media-bulk-move.json
+maeve media:bulk-label --workspace <id> --json media-bulk-labels.json
+maeve media:bulk-unlabel --workspace <id> --json media-bulk-labels.json
+maeve media:bulk-delete --workspace <id> --json media-ids.json --yes
+```
+
+### Content
+
+```bash
+maeve content:create --workspace <id> --json examples/create-content.json
+maeve content:update --workspace <id> --id <contentId> --json update-content.json
+maeve content:list --workspace <id> --status scheduled
+maeve content:list --workspace <id> --workflow-statuses approved,needs_changes
+maeve content:get --workspace <id> --id <contentId>
+maeve content:schedule --workspace <id> --id <contentId> --scheduled-at "2026-05-01T10:00:00+10:00"
+maeve content:intended-time --workspace <id> --id <contentId> --scheduled-at "2026-05-01T10:00:00+10:00"
+maeve content:notes --workspace <id> --id <contentId> --notes "<p>Planning notes</p>"
+maeve content:notes --workspace <id> --id <contentId> --json notes.json
+maeve content:workflow --workspace <id> --id <contentId> --status drafting
+maeve content:publish --workspace <id> --id <contentId> --yes
+maeve content:published-caption --workspace <id> --id <contentId> --json published-caption.json --yes
+maeve content:archive --workspace <id> --id <contentId>
+maeve content:restore --workspace <id> --id <contentId>
+maeve content:retry --workspace <id> --id <contentId>
+maeve content:delete --workspace <id> --id <contentId>
+maeve content:failed-count --workspace <id>
+maeve content:pending-approval-count --workspace <id>
+```
+
+Approvals, comments, and activity:
+
+```bash
+maeve content:approval-history --workspace <id>
+maeve content:approval-history:client-batch --workspace <id> --batch <batchId>
+maeve content:approval-history:internal --workspace <id> --record <recordId>
+maeve content:comment --workspace <id> --id <contentId> --json comment.json
+maeve content:comment-attachments:init --workspace <id> --json attachment.json
+maeve content:comment-attachments:complete --workspace <id> --attachment <attachmentId>
+maeve content:comment-attachments:abort --workspace <id> --attachment <attachmentId>
+maeve content:activity:react --workspace <id> --activity <activityId> --json reaction.json
+maeve content:activity:unreact --workspace <id> --activity <activityId> --emoji thumbs-up
+maeve content:request-approval --workspace <id> --id <contentId> --json approval.json --yes
+maeve content:decision --workspace <id> --id <contentId> --json decision.json
+maeve content:withdraw --workspace <id> --id <contentId>
+maeve content:resubmit --workspace <id> --id <contentId> --json approval.json --yes
+maeve content:history --workspace <id> --id <contentId>
+maeve content:reopen-client-review --workspace <id> --id <contentId>
+```
+
+### Client reviews
+
+```bash
+maeve client-reviews:create --workspace <id> --json client-review.json
+maeve client-reviews:open --workspace <id>
+maeve client-reviews:get --workspace <id> --batch <batchId>
+maeve client-reviews:add-post --workspace <id> --batch <batchId> --json post-id.json
+maeve client-reviews:remove-post --workspace <id> --batch <batchId> --json post-id.json
+maeve client-reviews:send --workspace <id> --batch <batchId> --yes
+maeve client-reviews:resend --workspace <id> --batch <batchId> --yes
+maeve client-reviews:cancel --workspace <id> --batch <batchId>
+maeve client-reviews:override --workspace <id> --batch <batchId> --json override.json
+maeve client-reviews:update-participant --workspace <id> --batch <batchId> --json participant.json
+maeve client-reviews:comment --workspace <id> --batch <batchId> --json comment.json
+```
+
+### Taxonomy and hashtags
+
+```bash
+maeve taxonomy:labels --workspace <id>
+maeve taxonomy:pillars --workspace <id>
+maeve taxonomy:formats --workspace <id>
+maeve hashtags:list --workspace <id>
+maeve hashtags:create --workspace <id> --json hashtags.json
+maeve hashtags:update --workspace <id> --id <hashtagGroupId> --json hashtags.json
+maeve hashtags:delete --workspace <id> --id <hashtagGroupId>
+```
+
+### Analytics
+
+```bash
+maeve analytics:summary --workspace <id> --days 30
+maeve analytics:summary --workspace <id> --integration <id> --days all
+maeve analytics:summary --workspace <id> --integration-ids <id,id>
+maeve analytics:health --workspace <id> --integration <id>
+maeve analytics:posts --workspace <id> --integration <id> --limit 12 --offset 0
+maeve analytics:posts-aggregate --workspace <id> --integration-ids <id,id> --sort-by views --days 30
+maeve analytics:post --workspace <id> --id <contentId>
+maeve analytics:demographics --workspace <id> --integration <id>
+maeve analytics:report --workspace <id> --provider instagram --json analytics-report.json --output report.pdf --yes
+```
+
+`analytics:summary` works on one integration or aggregates across many. Use `--integration-ids` to pick a set, or omit it for all accessible integrations. `--days` accepts `1` to `90` or `all`.
+
+`analytics:posts` is single-integration. `analytics:posts-aggregate` accepts `--integration-ids` and `--sort-by recent|engagement|views`.
+
+`analytics:report` is agency-plan only. It saves the PDF to `--output`. Stdout stays JSON metadata.
+
+### Inbox
+
+```bash
+maeve inbox:threads --workspace <id> --read unread
+maeve inbox:messages --workspace <id> --thread <threadId>
+maeve inbox:stats --workspace <id>
+maeve inbox:read --workspace <id> --thread <threadId>
+maeve inbox:unread --workspace <id> --thread <threadId>
+maeve inbox:read-all --workspace <id> --json inbox-read-all.json --yes
+maeve inbox:reply --workspace <id> --thread <threadId> --json inbox-reply.json --yes
+maeve inbox:note --workspace <id> --thread <threadId> --json inbox-note.json
+maeve inbox:moderate --workspace <id> --message <messageId> --json inbox-moderate.json --yes
+maeve inbox:retry-message --workspace <id> --message <messageId> --yes
+maeve inbox:delete-failed --workspace <id> --message <messageId> --yes
+```
+
+### Grid planner
+
+```bash
+maeve grid:list --workspace <id> --integration <integrationId>
+maeve grid:create --workspace <id> --json grid-item.json
+maeve grid:update --workspace <id> --item <itemId> --json grid-update.json
+maeve grid:delete --workspace <id> --item <itemId> --yes
+maeve grid:reorder --workspace <id> --json grid-reorder.json
+maeve grid:replace-media --workspace <id> --item <itemId> --json grid-media.json
+maeve grid:set-cover --workspace <id> --item <itemId> --json grid-cover.json
+maeve grid:remove-cover --workspace <id> --item <itemId>
+maeve grid:promote --workspace <id> --item <itemId> --json grid-promote.json --yes
+```
+
+## Payloads
+
+### Content
+
+`content:create` reads a JSON file and sends an `Idempotency-Key` header for safe retries. Pass `--idempotency-key <key>` to reuse a known key, or omit it to let the CLI generate one. Omitted `intent` defaults to `draft`; use `schedule` with `scheduledAt`, or `publish_now` plus CLI `--yes` for explicit immediate publishing. `content:update` uses the same shape except `intent`, but every accepted field is optional and at least one must be present.
+
+```json
+{
+  "integrationId": "00000000-0000-4000-8000-000000000001",
+  "intent": "draft",
+  "internalTitle": "Launch planning card",
+  "captions": {
+    "canonical": "Launch post copy"
+  },
+  "contentMedia": [
+    {
+      "mediaId": "00000000-0000-4000-8000-000000000007",
+      "order": 0,
+      "cover": {
+        "thumbOffsetMs": 2500
+      }
+    }
+  ],
+  "pillarIds": ["00000000-0000-4000-8000-000000000002"],
+  "formatIds": ["00000000-0000-4000-8000-000000000003"],
+  "labelIds": ["00000000-0000-4000-8000-000000000004"],
+  "campaignId": "00000000-0000-4000-8000-000000000005",
+  "campaignPhaseId": "00000000-0000-4000-8000-000000000006"
+}
+```
+
+Common fields:
+
+- `integrationId`: integration to post to.
+- `intent`: `draft`, `schedule`, or `publish_now`. Omitted intent defaults to `draft`.
+- `internalTitle`: internal planning title. Never published.
+- `publishTitle`: provider-facing title for platforms that support or require one.
+- `captions`: canonical publish text and optional platform overrides.
+- `notes`: internal rich-text notes. Never published. Max 100000 characters.
+- `contentMedia`: array of uploaded media relationships, with optional per-media crops, tags, and cover metadata.
+- `scheduledAt`: ISO 8601 with timezone, e.g. `2026-05-01T10:00:00+10:00`. Required only with `intent: "schedule"`.
+- `postType`: `post`, `reel`, `story`, or `thread`.
+- `settings`: provider settings from integration capabilities only. Media metadata belongs in `contentMedia`.
+- `firstComment`, `shareToFeed`: optional publish behavior fields.
+- `pillarIds`, `formatIds`, `labelIds`: arrays of workspace taxonomy UUIDs.
+- `campaignId`, `campaignPhaseId`: optional campaign links. Use `null` to clear when updating.
+- `priority`: `urgent`, `high`, `medium`, or `low`.
+- `threadMessages`: items for thread-style content using `captions` and optional `contentMedia`.
+
+`content:workflow` accepts only the user-mutable workflow statuses: `idea` or `drafting`.
+
+`content:published-caption` edits the provider caption for an already-published Facebook item and requires `--yes`.
+
+```json
+{
+  "message": "Updated Facebook caption"
+}
+```
+
+### Approvals and client reviews
+
+Approval and client review commands need an agency workspace plan and the role shown in each command's `--help`. Payloads mirror the public API DTOs.
+
+Internal approval request:
+
+```json
+{
+  "approverIds": ["00000000-0000-4000-8000-000000000001"],
+  "policy": "any"
+}
+```
+
+Client review batch:
+
+```json
+{
+  "contentIds": ["00000000-0000-4000-8000-000000000001"],
+  "workflowMode": "client",
+  "client": {
+    "reviewers": [{ "name": "Client Reviewer", "email": "reviewer@example.com" }],
+    "policy": "all",
+    "inviteNote": "Please review when you have a moment.",
+    "batchLabel": "May launch"
+  }
+}
+```
+
+Use `workflowMode: "internal_client"` with an `internal` object containing `approverIds` and `policy` when internal approval is required before client review.
+
+`content:create` requires `--yes` when the payload has `intent: "publish_now"`, `content:publish` requires `--yes` because it queues external publishing, and `content:published-caption` requires `--yes` because it edits already-published provider content. `content:request-approval`, `content:resubmit`, `client-reviews:send`, and `client-reviews:resend` all require `--yes` because they may notify people.
+
+### Inbox
+
+Inbox commands take explicit thread or message IDs. Public replies, moderation, retries, deletes, and `read-all` require `--yes`.
+
+Reply:
+
+```json
+{
+  "content": "Thanks for reaching out.",
+  "parentMessageId": "00000000-0000-4000-8000-000000000001"
+}
+```
+
+`content` is optional when an `attachment` is provided:
+
+```json
+{
+  "attachment": {
+    "type": "image",
+    "url": "https://cdn.example.com/reply.png"
+  }
+}
+```
+
+Internal note:
+
+```json
+{ "content": "Follow up with the team before replying." }
+```
+
+Moderation. Allowed actions: `hide`, `unhide`, `delete`.
+
+```json
+{ "action": "hide" }
+```
+
+Read-all takes the same filter shape as listing threads. Use `{}` only when you want all matching threads marked read.
+
+```json
+{
+  "platform": "instagram",
+  "status": "open",
+  "integrationId": "00000000-0000-4000-8000-000000000001",
+  "messageType": "comment"
+}
+```
+
+### Grid planner
+
+Visual-only item:
+
+```json
+{
+  "integrationId": "00000000-0000-4000-8000-000000000001",
+  "kind": "visual_only",
+  "mediaIds": ["00000000-0000-4000-8000-000000000002"],
+  "note": "Plan this visual",
+  "settings": { "aspectRatio": 1 }
+}
+```
+
+Linked content item:
+
+```json
+{
+  "integrationId": "00000000-0000-4000-8000-000000000001",
+  "kind": "linked_post",
+  "linkedContentId": "00000000-0000-4000-8000-000000000003"
+}
+```
+
+Reorder needs the full item ID order for the integration:
+
+```json
+{
+  "integrationId": "00000000-0000-4000-8000-000000000001",
+  "itemIds": ["00000000-0000-4000-8000-000000000004"]
+}
+```
+
+Media, cover, and promote payloads:
+
+```json
+{ "integrationId": "00000000-0000-4000-8000-000000000001", "mediaIds": ["00000000-0000-4000-8000-000000000002"] }
+```
+
+```json
+{ "integrationId": "00000000-0000-4000-8000-000000000001", "mediaId": "00000000-0000-4000-8000-000000000005" }
+```
+
+```json
+{ "integrationId": "00000000-0000-4000-8000-000000000001" }
+```
+
+`grid:delete` and `grid:promote` require `--yes`.
+
+### Media
+
+Supported upload extensions:
+
+- `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.avif`
+- `.mp4`, `.mov`
+
+Images cap at 50 MB, videos at 512 MB.
+
+Update payload:
+
+```json
+{
+  "filename": "campaign-hero.png",
+  "altText": "Campaign hero image",
+  "isFavorite": true,
+  "folderId": null
+}
+```
+
+Folder and label:
+
+```json
+{ "name": "Launch assets" }
+```
+
+```json
+{ "name": "Approved", "color": "#22cc88" }
+```
+
+Bulk payloads are explicit ID lists:
+
+```json
+{ "mediaIds": ["00000000-0000-4000-8000-000000000001"] }
+```
+
+```json
+{
+  "mediaIds": ["00000000-0000-4000-8000-000000000001"],
+  "labelIds": ["00000000-0000-4000-8000-000000000002"]
+}
+```
+
+`media:bulk-delete` moves active media to the Bin and requires `--yes`. Use `media:list --state deleted` to inspect Bin items.
+
+## License
+
+MIT (c) 2026 LILY DIA PTY LTD.

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+
+declare function createProgram(): Command;
+declare function runCli(argv?: string[]): Promise<void>;
+
+export { createProgram, runCli };