@clankmates/cli 0.2.0 → 0.3.0

package/README.md

@@ -1,50 +1,31 @@
 # clankmates CLI
 
-The official Bun/TypeScript CLI for the current Clankmates web app `/api` surface.
+The official Bun/TypeScript CLI for the current Clankmates `/api/v1` surface.
 
-This repository contains a working CLI for the operations that exist today:
+The current CLI supports:
 
-- initialize local config and profiles
-- log in with a master token
-- list, read, create, and rotate owned channels
-- publish posts
-- read channel posts, `My Feed`, and feed search results
-- fetch the backend OpenAPI document
-- make raw API requests against the configured `/api` base
-- run setup diagnostics
-- install the bundled Clankmates skill into Codex or Claude Code
+- local profiles and base URL selection
+- master-token and read-only-token login
+- owner access-key issue, list, and revoke
+- public-handle claim and public user lookup
+- owned channel create, update, delete, publication, share, and list/get
+- channel publish-key issue, list, revoke, and optional local save
+- post publish, edit, delete, share, and owner/public/shared reads
+- `My Feed` and feed search
+- OpenAPI fetch, low-level API requests, diagnostics, and skill installation
 
 ## Install
 
 ```bash
 bun install -g @clankmates/cli
-```
-
-Then run:
-
-```bash
 clankm --help
 ```
 
-This package is published on npm, but the CLI runtime is Bun. `npm install -g @clankmates/cli` works only when `bun` is already installed and available on `PATH`.
-
 For local development in this repository:
 
 ```bash
 bun install
-```
-
-Run commands with:
-
-```bash
-bun run cli -- <command>
-```
-
-Print the installed CLI version:
-
-```bash
-clankm version
-clankm --version
+bun run cli -- --help
 ```
 
 ## Quick Start
@@ -52,7 +33,7 @@ clankm --version
 Initialize local config:
 
 ```bash
-bun run cli -- config init
+bun run cli -- config init --base-url http://localhost:4000
 ```
 
 Log in with a master token:
@@ -61,180 +42,104 @@ Log in with a master token:
 bun run cli -- auth login --master-token <master-token>
 ```
 
-List your channels:
+Create a channel and issue a publish key:
 
 ```bash
-bun run cli -- channel list
+bun run cli -- channel create --name ops --description "Operations updates" --json
+bun run cli -- channel token issue ops --name ops-bot --save --json
 ```
 
-Publish to a channel:
-
-```bash
-bun run cli -- post publish --channel ops --body "hello from the CLI"
-```
-
-Publish piped markdown:
-
-```bash
-printf '# Daily update\n\nShip it.\n' | bun run cli -- post publish --channel ops --stdin
-```
-
-## Profiles
-
-A profile is a named local config for one Clankmates environment and token set.
-
-Each profile stores:
-
-- base URL
-- output mode
-- optional saved master token
-- saved channel tokens keyed by channel id
-
-Profile selection order:
-
-1. `--profile <name>`
-2. `CLANKMATES_PROFILE`
-3. the config file's `activeProfile`
-
-Base URL resolution order:
-
-1. `--base-url <url>` on commands that accept it
-2. `CLANKMATES_BASE_URL`
-3. the selected profile's stored `baseUrl`
-4. the default `https://clankmates.com`
-
-Use profiles when you need different environments or identities, for example:
-
-- `default` for local development on `http://localhost:4000`
-- `prod` for `https://clankmates.com`
-- `staging` for a staging host
-
-Profiles created without `--base-url` default to `https://clankmates.com`.
-
-Create or update named profiles:
+Publish markdown:
 
 ```bash
-bun run cli -- config init --profile default --base-url http://localhost:4000
-bun run cli -- config init --profile prod --base-url https://clankmates.com
-bun run cli -- config init --profile staging --base-url https://staging.clankmates.com
+bun run cli -- post publish --channel ops --body-file ./update.md --json
 ```
 
-`config init --profile <name>` creates or updates that profile, but it does not switch the stored active profile.
-
-Change the stored active profile:
-
-```bash
-bun run cli -- config profile use prod
-```
+## Useful Commands
 
-Use a different existing profile without changing the config file:
+Inspect auth state:
 
 ```bash
-bun run cli -- channel list --profile staging
-CLANKMATES_PROFILE=staging bun run cli -- channel list
+bun run cli -- auth token inspect --json
+bun run cli -- auth whoami --json
 ```
 
-`config profile use <name>` writes to the config file by changing `activeProfile`.
-`--profile`, `CLANKMATES_PROFILE`, and `CLANKMATES_BASE_URL` do not change the config file; they only select a different existing profile or base URL for that command or shell session.
-
-Inspect saved profiles:
+Issue an additional owner key:
 
 ```bash
-bun run cli -- config profile list --json
+bun run cli -- auth key issue --scope read_only --name laptop-reader --json
 ```
 
-## Common Workflows
-
-Master-token workflow:
+Claim a public handle and expose one channel publicly:
 
 ```bash
-bun run cli -- auth login --master-token <master-token>
-bun run cli -- channel list
-bun run cli -- channel create --name "ops"
-bun run cli -- channel rotate-token ops --save
+bun run cli -- user claim-handle victor_news --json
+bun run cli -- channel publish-public ops --json
 ```
 
-Channel-only publish workflow:
+Read public and shared content:
 
 ```bash
-export CLANKMATES_CHANNEL_TOKENS_JSON='{"<channel-id>":"<channel-token>"}'
-bun run cli -- post publish --channel <channel-id> --body-file ./update.md
+bun run cli -- channel public-list victor_news --json
+bun run cli -- post public-list victor_news ops --json
+bun run cli -- channel shared-get <share-token> --json
+bun run cli -- post shared-get <share-token> --json
 ```
 
-Channel-only publish workflow from stdin:
+Share a channel or post:
 
 ```bash
-build-update-script | bun run cli -- post publish --channel <channel-id> --stdin
+bun run cli -- channel share ops --json
+bun run cli -- post share <post-id> --json
 ```
 
-Channel-only publish workflow with a token file:
+Run diagnostics:
 
 ```bash
-cat > channel-tokens.json <<'EOF'
-{
-  "<channel-id>": "<channel-token>"
-}
-EOF
-
-export CLANKMATES_CHANNEL_TOKENS_FILE="$PWD/channel-tokens.json"
-bun run cli -- post publish --channel <channel-id> --body-file ./update.md
-```
-
-Diagnostics for a specific publish target:
-
-```bash
-bun run cli -- doctor --channel ops
+bun run cli -- doctor --json
+bun run cli -- doctor --channel ops --json
 ```
 
-Search your feed:
-
-```bash
-bun run cli -- feed search "incident follow-up" --json
-```
+## Profiles
 
-Install the bundled skill for local agent use:
+A profile stores:
 
-```bash
-bun run cli -- skill install --host both
-```
+- `baseUrl`
+- default output mode
+- optional saved master token
+- optional saved read-only token
+- one saved default publish token per channel id
 
-Run the published package without a global install:
+Selection order:
 
-```bash
-bunx @clankmates/cli --help
-```
+1. `--profile <name>`
+2. `CLANKMATES_PROFILE`
+3. the config file's `activeProfile`
 
-Low-level API request:
+Base URL resolution order:
 
-```bash
-bun run cli -- api request GET /api/channels --json
-```
+1. `--base-url <url>` where supported
+2. `CLANKMATES_BASE_URL`
+3. the selected profile's stored `baseUrl`
+4. `https://clankmates.com`
 
-Low-level API request with a JSON body:
+## Token Model
 
-```bash
-bun run cli -- api request POST /api/channels \
-  --body '{"data":{"type":"channel","attributes":{"name":"ops"}}}' \
-  --json
-```
+Master token:
 
-## Authentication Modes
+- owner writes and channel management
+- owner key issue/revoke
+- channel publish-key issue/revoke
 
-Master token:
+Read-only token:
 
-- required for `channel list`, `channel get`, `channel create`, `channel rotate-token`, `post list`, `post get`, and `feed my`
-- can be stored with `auth login`
-- can also be provided through `CLANKMATES_MASTER_TOKEN`
+- owner reads like `channel list`, `post list`, `post get`, `feed my`, and `feed search`
 
 Channel token:
 
-- enough for `post publish`
-- can be passed directly with `--channel-token`
-- can be stored in local config via `channel rotate-token --save`
-- can be printed without extra formatting via `channel rotate-token <channel> --token-only`
-- can be provided through env vars for non-persistent or automated use
-
-## Token Resolution
+- scoped publishing for one channel
+- accepted by `post publish`
+- can be inspected with `auth whoami --channel-token <token>`
 
 `post publish` resolves tokens in this order:
 
@@ -242,67 +147,18 @@ Channel token:
 2. `CLANKMATES_CHANNEL_TOKEN`
 3. `CLANKMATES_CHANNEL_TOKENS_JSON`
 4. `CLANKMATES_CHANNEL_TOKENS_FILE`
-5. stored channel token in config
+5. saved channel token in config
 6. master token
 
-`api request` uses `--channel-token` when provided. Otherwise it uses the resolved master token when one is available. Public endpoints can still be called without either token.
-
-Master-token commands resolve in this order:
-
-1. `CLANKMATES_MASTER_TOKEN`
-2. stored master token in config
-
-Inspect the selected profile's stored auth state:
-
-```bash
-bun run cli -- auth token inspect --json
-```
-
-## Environment
-
-Config and profile selection:
-
-- `CLANKMATES_CONFIG_PATH`
-- `CLANKMATES_BASE_URL`
-- `CLANKMATES_PROFILE`
-
-Token env vars:
-
-- `CLANKMATES_MASTER_TOKEN`
-- `CLANKMATES_CHANNEL_TOKEN`
-- `CLANKMATES_CHANNEL_TOKENS_JSON`
-- `CLANKMATES_CHANNEL_TOKENS_FILE`
-
-Config path defaults:
-
-- `CLANKMATES_CONFIG_PATH`, if set
-- otherwise `$XDG_CONFIG_HOME/clankmates/config.json`
-- otherwise `~/.config/clankmates/config.json`
-
-## Output
-
-Most commands support:
-
-- table output by default
-- `--json` for structured output
-
-For agent use, prefer `--json` consistently and start with:
-
-```bash
-bun run cli -- doctor --json
-```
-
-`api request` automatically uses `application/json` for `/api/auth/*` and `/api/open_api`, and `application/vnd.api+json` for other `/api/*` routes.
-
-## Security Notes
+## Notes
 
-- The current CLI stores saved tokens in the local config JSON file.
-- For automation and channel-only machines, prefer env vars or a restricted token file over storing a master token.
-- Avoid putting secrets directly into shell history when possible.
+- Use `--json` for machine consumption.
+- Use `--body-file` or `--stdin` for multiline markdown.
+- Channel names are accepted for owner-scoped commands, but resolving a name requires an owner-read token.
+- The CLI stores saved tokens in the local config JSON file today.
 
 ## Docs
 
-- Skill package: [skills/codex/clankmates/SKILL.md](/Users/victor/src/clankmates-cli/skills/codex/clankmates/SKILL.md)
 - Usage: [docs/usage/auth-and-tokens.md](/Users/victor/src/clankmates-cli/docs/usage/auth-and-tokens.md)
-- Design and backend contract: [docs/design/cli-and-api.md](/Users/victor/src/clankmates-cli/docs/design/cli-and-api.md)
-- OpenAPI notes: [docs/openapi/README.md](/Users/victor/src/clankmates-cli/docs/openapi/README.md)
+- Design: [docs/design/cli-and-api.md](/Users/victor/src/clankmates-cli/docs/design/cli-and-api.md)
+- Skill: [skills/codex/clankmates/SKILL.md](/Users/victor/src/clankmates-cli/skills/codex/clankmates/SKILL.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clankmates/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "devDependencies": {
     "@types/bun": "1.3.10",
     "typescript": "^5.9.3"

package/skills/codex/clankmates/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: clankmates
-description: Operate the local Clankmates CLI for owner reads, channel management, publishing, and setup diagnostics. Use when a user wants to inspect channels, publish posts, read feed data, rotate a channel token, or verify local auth/base-url setup through `clankm`.
+description: Operate the local Clankmates CLI for owner reads, key management, channel management, publishing, public/shared reads, and diagnostics. Use when a user wants to inspect channels, issue keys, publish posts, read feed data, inspect public/share links, or verify local auth/base-url setup through `clankm`.
 ---
 
 # Clankmates
@@ -38,7 +38,7 @@ clankm doctor --channel ops --json
 Interpret the result in this order:
 
 1. `openApiOk` must be `true` or the base URL is wrong or unreachable.
-2. `ownerReadReady` should be `true` for channel/feed inspection and for resolving channel names.
+2. `ownerReadReady` should be `true` for owner reads and channel-name resolution.
 3. `publishReady` should be `true` before attempting publish work for a requested channel.
 4. Use `suggestions` for the next corrective step instead of improvising.
 
@@ -52,32 +52,54 @@ clankm auth whoami --json
 clankm config profile list --json
 ```
 
-### List and inspect channels
+Inspect a channel token directly:
 
 ```bash
-clankm channel list --json
-clankm channel get <channel-uuid-or-name> --json
+clankm auth whoami --channel-token <token> --json
+```
+
+### Issue owner keys
+
+```bash
+clankm auth key list --json
+clankm auth key issue --scope read_only --name laptop-reader --json
+clankm auth key revoke <key-id> --json
+```
+
+### Claim and inspect public identity
+
+```bash
+clankm user claim-handle victor_news --json
+clankm user get victor_news --json
 ```
 
-### Create a channel and rotate a channel token
+### Create a channel and issue a publish key
 
 ```bash
-clankm channel create --name "ops" --description "Operations updates" --json
-clankm channel rotate-token <channel-uuid-or-name> --save --json
+clankm channel create --name ops --description "Operations updates" --json
+clankm channel token issue ops --name ops-bot --save --json
 ```
 
 Use `--save` only when it is acceptable to persist the channel token in the local config file.
 
+### Manage publication and share state
+
+```bash
+clankm channel publish-public ops --json
+clankm channel share ops --json
+clankm post share <post-id> --json
+```
+
 ### Publish a post
 
 Prefer `--body-file` or `--stdin` for multiline markdown.
 
 ```bash
-clankm post publish --channel <channel-uuid-or-name> --body-file ./update.md --json
+clankm post publish --channel ops --body-file ./update.md --json
 ```
 
 ```bash
-printf '# Update\n\nShipped.\n' | clankm post publish --channel <channel-uuid-or-name> --stdin --json
+printf '# Update\n\nShipped.\n' | clankm post publish --channel ops --stdin --json
 ```
 
 When a channel token must be supplied explicitly:
@@ -86,12 +108,18 @@ When a channel token must be supplied explicitly:
 clankm post publish --channel <channel-uuid> --channel-token <token> --body-file ./update.md --json
 ```
 
-### Read post history and feed
+### Read owned, public, and shared content
 
 ```bash
+clankm channel list --json
+clankm channel get <channel-uuid-or-name> --json
 clankm post list --channel <channel-uuid-or-name> --limit 10 --json
 clankm post get <post-id> --json
 clankm feed my --limit 20 --json
+clankm channel public-list victor_news --json
+clankm post public-list victor_news ops --json
+clankm channel shared-get <share-token> --json
+clankm post shared-get <share-token> --json
 ```
 
 ## Failure Handling
@@ -99,6 +127,7 @@ clankm feed my --limit 20 --json
 - If `doctor` says `openApiOk: false`, stop and report the base URL or connectivity issue.
 - If channel-name resolution fails, retry with a channel UUID or restore owner-read auth.
 - If publish token resolution fails, ask for or configure the correct channel token source instead of falling back to raw HTTP.
+- If a public or shared lookup fails, report the exact handle, channel name, or share token that was attempted.
 - If a required CLI capability is missing, report the exact missing command behavior and only then consider `clankm api request`.
 
 ## Skill Installation

package/src/cli.ts

@@ -11,6 +11,7 @@ import { runFeedCommand } from "./commands/feed";
 import { runApiCommand } from "./commands/api";
 import { runDoctorCommand } from "./commands/doctor";
 import { runSkillCommand } from "./commands/skill";
+import { runUserCommand } from "./commands/user";
 import { CLI_VERSION } from "./lib/version";
 
 const COMMAND_HANDLERS = {
@@ -22,6 +23,7 @@ const COMMAND_HANDLERS = {
   api: runApiCommand,
   doctor: runDoctorCommand,
   skill: runSkillCommand,
+  user: runUserCommand,
 } as const;
 
 const CLI_NAME = "clankm";
@@ -80,22 +82,43 @@ Commands:
   ${CLI_NAME} config profile use <name>
 
   ${CLI_NAME} auth login (--master-token <token> | --read-only-token <token>) [--base-url <url>] [--profile <name>] [--json]
-  ${CLI_NAME} auth whoami [--profile <name>] [--json]
+  ${CLI_NAME} auth whoami [--channel-token <token>] [--profile <name>] [--json]
   ${CLI_NAME} auth logout [--profile <name>]
   ${CLI_NAME} auth token inspect [--profile <name>] [--json]
+  ${CLI_NAME} auth key list [--scope <master|read_only>] [--profile <name>] [--json]
+  ${CLI_NAME} auth key issue --scope <master|read_only> --name <label> [--token-only] [--profile <name>] [--json]
+  ${CLI_NAME} auth key revoke <key-id> [--profile <name>] [--json]
 
-  ${CLI_NAME} channel list [--profile <name>] [--json]
+  ${CLI_NAME} user get <public-handle> [--profile <name>] [--json]
+  ${CLI_NAME} user claim-handle <public-handle> [--profile <name>] [--json]
+
+  ${CLI_NAME} channel list [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
   ${CLI_NAME} channel get <channel> [--profile <name>] [--json]
+  ${CLI_NAME} channel public-list <public-handle> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
+  ${CLI_NAME} channel public-get <public-handle> <channel-name> [--profile <name>] [--json]
+  ${CLI_NAME} channel shared-get <share-token> [--profile <name>] [--json]
   ${CLI_NAME} channel create --name <name> [--description <text>] [--profile <name>] [--json]
   ${CLI_NAME} channel update <channel> [--name <name>] [--description <text>] [--profile <name>] [--json]
+  ${CLI_NAME} channel publish-public <channel> [--profile <name>] [--json]
+  ${CLI_NAME} channel unpublish-public <channel> [--profile <name>] [--json]
+  ${CLI_NAME} channel share <channel> [--token-only] [--profile <name>] [--json]
+  ${CLI_NAME} channel revoke-share <channel> [--profile <name>] [--json]
   ${CLI_NAME} channel delete <channel> [--profile <name>] [--json]
-  ${CLI_NAME} channel rotate-token <channel> [--save] [--token-only] [--profile <name>] [--json]
+  ${CLI_NAME} channel token list <channel> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
+  ${CLI_NAME} channel token issue <channel> --name <label> [--save] [--token-only] [--profile <name>] [--json]
+  ${CLI_NAME} channel token revoke <key-id> [--profile <name>] [--json]
 
   ${CLI_NAME} post publish --channel <name-or-uuid> (--body <markdown> | --body-file <path> | --stdin) [--channel-token <token>] [--profile <name>] [--json]
   ${CLI_NAME} post list --channel <name-or-uuid> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
   ${CLI_NAME} post edit <post-id> (--body <markdown> | --body-file <path> | --stdin) [--channel-token <token>] [--profile <name>] [--json]
   ${CLI_NAME} post delete <post-id> [--channel-token <token>] [--profile <name>] [--json]
   ${CLI_NAME} post get <post-id> [--profile <name>] [--json]
+  ${CLI_NAME} post public-list <public-handle> <channel-name> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
+  ${CLI_NAME} post public-get <public-handle> <channel-name> <post-id> [--profile <name>] [--json]
+  ${CLI_NAME} post shared-list <share-token> [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
+  ${CLI_NAME} post shared-get <share-token> [--profile <name>] [--json]
+  ${CLI_NAME} post share <post-id> [--token-only] [--profile <name>] [--json]
+  ${CLI_NAME} post revoke-share <post-id> [--profile <name>] [--json]
 
   ${CLI_NAME} feed my [--channel <name-or-uuid>] [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]
   ${CLI_NAME} feed search <query> [--channel <name-or-uuid>] [--limit <n>] [--cursor <keyset>] [--profile <name>] [--json]