@graphlit/durable-agents 1.0.20260614002 → 1.0.20260615005

package/README.md

@@ -1,33 +1,268 @@
 # Graphlit Durable Agents CLI
 
-Command-line interface for Durable Agents.
+The Durable CLI is the terminal surface for [Graphlit Durable Agents](https://www.durableagents.ai). Use it to authenticate a Durable workspace, connect source accounts, create synced data sources, manage Library content, configure agents, start and inspect runs, browse the read-only `/library` virtual filesystem, and wire agents to channels or MCP connectors.
+
+The npm package is `@graphlit/durable-agents`. The executable is `durable`.
+
+## Install
+
+Requires Node.js `>=22.20.0`.
 
 ```bash
 npm install -g @graphlit/durable-agents
+
+durable --version
 durable --help
 ```
 
-The CLI defaults to the production Durable Agents API and uses `--json` for stable machine-readable output.
+The CLI talks to the production Durable Agents API by default.
+
+## First Session
+
+Authenticate once on each machine:
 
 ```bash
 durable login
+durable whoami
+durable status
+```
+
+Then inspect the workspace:
+
+```bash
+durable usage
+durable models list
+durable accounts list
+durable sources list
+durable agents list
+durable library list
+durable runs list
+```
+
+Create and run a minimal agent:
+
+```bash
+AGENT_ID="$(
+  durable --json agents create \
+    --name "CLI Assistant" \
+    --prompt "Answer from Library context when available." \
+  | jq -r '.id'
+)"
+
+durable library ingest \
+  --text "Sprint notes: focus on onboarding, channels, and CLI polish." \
+  --name "Sprint Notes" \
+  --label planning
+
+durable agents start "$AGENT_ID" "Summarize the sprint notes."
 ```
 
-Login opens Durable Agents Hub, shows a pairing code in both the terminal and browser, and stores a claimed Durable API key in the local credentials file.
+`durable agents start` streams by default. For scripts, use `--json`, `--no-stream`, `--wait`, and `--timeout` when you need structured or bounded output.
+
+## Agent Skills
 
-Agent mutations use the property-oriented grammar:
+The README intentionally stays compact. The canonical task guides live in the [Graphlit skills repo](https://github.com/graphlit/skills):
+
+| Skill | Use it for |
+| --- | --- |
+| [durable-cli](https://github.com/graphlit/skills/blob/main/skills/durable-cli/SKILL.md) | Installing, authenticating, scripting, connecting accounts, creating data sources, operating agents/runs, using Library/VFS commands, channels, email, messaging, and MCP connectors. |
+| [durable-cli quickstart](https://github.com/graphlit/skills/blob/main/skills/durable-cli/references/quickstart.md) | The fastest path from install to a working Durable Agents session. |
+| [durable-cli command surface](https://github.com/graphlit/skills/blob/main/skills/durable-cli/references/command-surface.md) | Choosing the right command family and avoiding naming mistakes such as accounts vs sources vs connectors vs channels. |
+| [graphlit](https://github.com/graphlit/skills/blob/main/skills/graphlit/SKILL.md) | Building Graphlit-powered apps with ingestion, retrieval, collections, feeds, specifications, knowledge graph workflows, and `streamAgent()`. |
+| [graphlit-agent-tools](https://github.com/graphlit/skills/blob/main/skills/graphlit-agent-tools/SKILL.md) | Giving tool-calling agents Graphlit retrieval, content inspection, resource reading, ingestion, enrichment, and media-generation tools through `@graphlit/agent-tools`. |
+
+When you are asking a coding agent to use the CLI, point it at the `durable-cli` skill instead of copying command details into your prompt.
+
+## Common Workflows
+
+### Auth And Keys
+
+```bash
+durable login
+durable logout
+durable whoami
+durable status
+
+durable auth import --stdin
+durable auth import --env DURABLE_API_KEY
+durable auth export
+
+durable keys list
+durable keys create --name "CI"
+durable keys create --name "CI" --save
+durable keys revoke <api-key-id>
+```
+
+Local credentials are stored at `~/.config/graphlit/durable-agents/credentials.json`. `DURABLE_API_KEY` takes precedence over the stored credential.
+
+### Agents And Runs
+
+```bash
+durable agents list
+durable agents create --name "Research Assistant"
+durable agents get <agent>
+durable agents set <agent> prompt "Answer from the Library."
+durable agents start <agent> "Summarize recent planning notes."
+
+durable runs list --agent <agent>
+durable runs get <run-id>
+durable runs watch <run-id>
+durable runs prompt <run-id> "Now turn that into three action items."
+durable runs replay <run-id>
+durable runs pause <run-id>
+durable runs resume <run-id> --reply "Approved."
+durable runs cancel <run-id>
+```
+
+Agent edits use the property grammar:
 
 ```bash
 durable agents set <agent> prompt "Run the daily account sweep."
 durable agents set <agent> prompt --file ./prompt.md
 durable agents set <agent> schedule.cron "0 7 * * 1-5"
 durable agents set <agent> trigger.kinds text page
+durable agents set <agent> mode interactive
 durable agents clear <agent> focus
-durable agents clear <agent> trigger.kinds
 ```
 
-Scalar values are positional by default. List-valued properties use repeated
-positional values. The global `--json` flag controls output only; it is not an
-input parser.
+Scalar values are positional. List-valued properties use repeated positional values. The global `--json` flag controls output only; it is not an input parser.
+
+### Library And VFS
+
+```bash
+durable library list
+durable library ingest --url "https://example.com/docs" --name "Docs Home" --label docs
+durable library ingest --text "Customer asked about onboarding." --name "Customer Note"
+durable library upload ./README.md --label repo --wait
+durable library search "planning"
+durable library inspect <content-id>
+
+durable fs ls /library
+durable fs ls /library/labels/docs --long
+durable fs find /library --kind document --long
+durable fs grep "onboarding" /library
+durable fs sgrep "accounts likely to expand" /library
+durable fs cat /library/<content-id>
+durable fs stat /library/<content-id>
+```
+
+Use `durable library ...` to manage content objects. Use `durable fs ...` to navigate and search the derived `/library` filesystem view.
+
+### Source Accounts And Data Sources
+
+```bash
+durable accounts connect github
+durable accounts list
+durable accounts reconnect <account>
+
+durable sources create web --name "Docs Web" --url "https://example.com/docs"
+durable sources discover github --account <account> --search repo-name
+durable sources create github-code --account <account> --repo owner/repo
+durable sources sync <source>
+durable sources pause <source>
+durable sources resume <source>
+```
+
+Use `accounts` for external account OAuth state. Use `sources` for the synced external content Durable should ingest. Use `connectors` only for MCP servers.
+
+### MCP Connectors And Channels
+
+```bash
+durable connectors create https://example.com/mcp --name "Example MCP" --type http
+durable connectors connect <connector>
+durable connectors list
+
+durable channels setup slack
+durable channels create slack --name "Workspace Slack" --bot-token "xoxb-..." --signing-secret "<secret>"
+durable channels endpoints --provider slack --query ops
+durable channels bind --provider slack --agent <agent> --channel "#ops" --workspace "My Workspace"
+
+durable channels email create
+durable channels email messages send <email-address> --to user@example.com --subject "Hello" --text "READY"
+durable channels messaging status
+durable channels messaging phones register --phone +15555550123
+```
+
+## JSON And Scripting
+
+Put global flags before the command group:
+
+```bash
+durable --json agents list
+durable --quiet runs watch <run-id>
+durable --verbose status
+durable --debug status
+```
+
+Capture IDs with `--json` for reliable automation:
+
+```bash
+AGENT_ID="$(durable --json agents create --name "Scripted Agent" | jq -r '.id')"
+RUN_ID="$(durable --json agents start "$AGENT_ID" --no-stream "Reply READY only." | jq -r '.id')"
 
-The older `durable agents update ...` flags remain available for compatibility.
+durable --json runs get "$RUN_ID"
+```
+
+Prompt text can be positional, read from `--file`, or piped through stdin:
+
+```bash
+durable agents start <agent> "Review this."
+durable agents start <agent> --file ./prompt.md
+cat ./prompt.md | durable agents start <agent>
+```
+
+## Command Map
+
+```text
+durable login | logout | whoami | status
+durable auth import | export
+durable keys list | create | revoke
+durable usage
+durable wallet fund | fund status
+durable models list
+
+durable agents list | create | get | set | clear | start | update | delete
+durable runs list | get | events | watch | replay | pause | resume | prompt | cancel
+
+durable personas list | create | get | update | delete
+durable skills list | create | get | update | delete
+
+durable library list | ingest | upload | get | inspect | update | delete | search
+durable fs ls | cat | grep | sgrep | find | stat
+
+durable accounts list | connect | get | reconnect | delete
+durable sources list | get | discover | create | update | pause | resume | sync | delete
+
+durable connectors list | create | get | update | connect | disconnect | delete
+durable channels setup slack
+durable channels list | create | delete | endpoints | bind | unbind
+durable channels email list | create | delete
+durable channels email messages list | get | send
+durable channels messaging status
+durable channels messaging phones register | list | delete
+```
+
+When details matter, ask the installed CLI:
+
+```bash
+durable agents start --help
+durable sources create --help
+durable channels bind --help
+durable fs sgrep --help
+```
+
+## Development
+
+This package is built from `apps/durable-cli`.
+
+```bash
+npm run generate
+npm run build
+npm run check
+```
+
+For local API development:
+
+```bash
+export DURABLE_API_BASE_URL="http://localhost:3000"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphlit/durable-agents",
-  "version": "1.0.20260614002",
+  "version": "1.0.20260615005",
   "private": false,
   "type": "module",
   "bin": {