twentythree-cli 1.0.0

package/docs/commands/workspace/list.md

@@ -0,0 +1,27 @@
+`twentythree workspace:list`
+============================
+
+List all configured workspaces
+
+* [`twentythree workspace list`](#twentythree-workspace-list)
+
+## `twentythree workspace list`
+
+List all configured workspaces
+
+```
+USAGE
+  $ twentythree workspace list [--json] [-w <value>]
+
+GLOBAL FLAGS
+  -w, --workspace=<value>  Workspace domain or display name to use for this invocation.
+      --json               Format output as json.
+
+DESCRIPTION
+  List all configured workspaces
+
+EXAMPLES
+  $ twentythree workspace list
+```
+
+_See code: [src/commands/workspace/list.ts](https://github.com/23/twentythree-cli/blob/v0.1.0/src/commands/workspace/list.ts)_

package/docs/commands/workspace/use.md

@@ -0,0 +1,32 @@
+`twentythree workspace:use`
+===========================
+
+Switch the active workspace
+
+* [`twentythree workspace use NAME`](#twentythree-workspace-use-name)
+
+## `twentythree workspace use NAME`
+
+Switch the active workspace
+
+```
+USAGE
+  $ twentythree workspace use NAME [--json] [-w <value>]
+
+ARGUMENTS
+  NAME  Workspace domain or display name
+
+GLOBAL FLAGS
+  -w, --workspace=<value>  Workspace domain or display name to use for this invocation.
+      --json               Format output as json.
+
+DESCRIPTION
+  Switch the active workspace
+
+EXAMPLES
+  $ twentythree workspace use company.video23.com
+
+  $ twentythree workspace use "Company Name"
+```
+
+_See code: [src/commands/workspace/use.ts](https://github.com/23/twentythree-cli/blob/v0.1.0/src/commands/workspace/use.ts)_

package/docs/commands/workspace.md

@@ -0,0 +1,54 @@
+`twentythree workspace`
+=======================
+
+List all configured workspaces
+
+* [`twentythree workspace list`](#twentythree-workspace-list)
+* [`twentythree workspace use NAME`](#twentythree-workspace-use-name)
+
+## `twentythree workspace list`
+
+List all configured workspaces
+
+```
+USAGE
+  $ twentythree workspace list [--json] [-w <value>]
+
+GLOBAL FLAGS
+  -w, --workspace=<value>  Workspace domain or display name to use for this invocation.
+      --json               Format output as json.
+
+DESCRIPTION
+  List all configured workspaces
+
+EXAMPLES
+  $ twentythree workspace list
+```
+
+_See code: [src/commands/workspace/list.ts](https://github.com/23/twentythree-cli/blob/v0.1.0/src/commands/workspace/list.ts)_
+
+## `twentythree workspace use NAME`
+
+Switch the active workspace
+
+```
+USAGE
+  $ twentythree workspace use NAME [--json] [-w <value>]
+
+ARGUMENTS
+  NAME  Workspace domain or display name
+
+GLOBAL FLAGS
+  -w, --workspace=<value>  Workspace domain or display name to use for this invocation.
+      --json               Format output as json.
+
+DESCRIPTION
+  Switch the active workspace
+
+EXAMPLES
+  $ twentythree workspace use company.video23.com
+
+  $ twentythree workspace use "Company Name"
+```
+
+_See code: [src/commands/workspace/use.ts](https://github.com/23/twentythree-cli/blob/v0.1.0/src/commands/workspace/use.ts)_

package/docs/guides/api-spec-upgrade.md

@@ -0,0 +1,92 @@
+# Updating the API Spec
+
+## Overview
+
+The TwentyThree API evolves over time. When the upstream OpenAPI spec changes, the CLI's type definitions and any affected commands need to be updated to stay in sync. This guide walks through the full update workflow — from downloading the latest spec to committing the changes.
+
+## Prerequisites
+
+- pnpm (workspace-level dependency management)
+- Claude Code (for assisted command fixes)
+- The repo cloned and dependencies installed (`pnpm install`)
+
+## Step 1: Run the update script
+
+From the repo root:
+
+```bash
+pnpm update-api-spec
+```
+
+Or from inside the CLI package directory:
+
+```bash
+cd packages/twentythree-cli && ./update-api-spec.sh
+```
+
+The script does three things:
+
+1. Downloads the latest OpenAPI spec to `packages/twentythree-cli/specs/twentythree-api-swagger.json`
+2. Prints a `git diff` of the spec file showing what changed
+3. Runs `pnpm generate-types` to regenerate `src/api/types.ts` from the updated spec
+
+## Step 2: Read the diff output
+
+The script prints a raw `git diff` of the JSON spec file. When reading the diff, look for:
+
+- **New `paths` entries** — new API endpoints that may need new CLI commands
+- **Removed `paths` entries** — endpoints that no longer exist; existing commands may break
+- **Changed `parameters` or `requestBody` under an existing path** — TypeScript errors will surface these when you compile
+- **Changed `responses` shapes** — TypeScript errors will surface these too
+
+Example: a new endpoint being added looks like this in the diff:
+
+```diff
++    "/api/video/analytics/engagement": {
++      "get": {
++        "operationId": "getVideoAnalyticsEngagement",
++        "parameters": [...]
++      }
++    },
+```
+
+## Step 3: Apply changes with Claude Code
+
+First, capture any TypeScript errors introduced by the updated types:
+
+```bash
+pnpm --filter twentythree-cli exec tsc --noEmit
+```
+
+Then:
+
+1. Open a Claude Code session
+2. Paste the diff output and any TypeScript errors into the session
+3. Ask Claude to update affected command files and fix broken types
+
+Note: The codebase may have pre-existing type errors unrelated to the spec change. Focus on errors that are newly introduced after running the update script — not pre-existing ones.
+
+## Step 4: Verify
+
+Run both checks to confirm the update is clean:
+
+```bash
+pnpm --filter twentythree-cli exec tsc --noEmit
+pnpm --filter twentythree-cli test --run
+```
+
+Both should complete without new errors introduced by the spec update.
+
+## Step 5: Commit
+
+Commit these files together in a single commit:
+
+- `packages/twentythree-cli/specs/twentythree-api-swagger.json` (updated spec)
+- `packages/twentythree-cli/src/api/types.ts` (regenerated types)
+- Any command files updated to match the new spec
+
+Example commit message:
+
+```
+chore: update API spec and regenerate types (YYYY-MM-DD)
+```

package/docs/guides/getting-started.md

@@ -0,0 +1,66 @@
+# Getting Started
+
+## Prerequisites
+
+- Node.js 22 or later
+- Install the CLI globally:
+
+```bash
+npm install -g twentythree-cli
+```
+
+## Step 1: Add your credentials
+
+The CLI stores your TwentyThree domain and bearer token in the OS keychain. You only need to do this once per workspace.
+
+```bash
+twentythree auth credentials
+```
+
+The command prompts you for your domain and bearer token:
+
+```
+Domain (e.g. company.video23.com): company.video23.com
+Bearer token (press Enter to skip for anonymous access): ••••••••
+```
+
+After you enter a bearer token, the CLI automatically discovers all workspaces associated with your token and sets the first one as active. If your token has access to multiple workspaces, you will be prompted to select a default.
+
+## Step 2: Select a workspace
+
+If your token has access to multiple workspaces, you can list them and switch between them at any time.
+
+```bash
+twentythree workspace list
+twentythree workspace use company.video23.com
+```
+
+## Step 3: Run your first command
+
+List the videos in your active workspace.
+
+```bash
+twentythree video list
+```
+
+Sample output:
+
+```
+ ID        Title                        Duration  Status   Published  Updated
+ ─────────────────────────────────────────────────────────────────────────────
+ 12345678  Introduction to TwentyThree  2:34      encoded  yes        2024-03-15
+ 12345679  Product Demo Q1              5:12      encoded  yes        2024-03-10
+ 12345680  Webinar Recap                48:00     encoded  no         2024-03-08
+3 videos
+```
+
+## Next steps
+
+Browse all 244 commands in the [Command Reference](../commands/README.md).
+
+Run `twentythree <topic> --help` for help on any topic. For example:
+
+```bash
+twentythree video --help
+twentythree auth --help
+```