Graphlit Durable Agents CLI

The Durable CLI is the terminal surface for Graphlit Durable Agents. Use it to authenticate a Durable workspace, connect source accounts, create synced data sources, manage Library content, configure agents, prompt interactive agents, 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.

npm install -g @graphlit/durable-agents

durable --version
durable --help

The CLI talks to the production Durable Agents API by default.

First Session

Authenticate once on each machine:

durable login
durable whoami
durable status

Then inspect the workspace:

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:

AGENT_ID="$(durable --json agents create --name "CLI Assistant" | jq -r '.id')"

durable library ingest \
  --text "Sprint notes: focus on onboarding, channels, and CLI polish." \
  --name "Sprint Notes" \
  --label planning

durable agents prompt "$AGENT_ID" "Summarize the sprint notes."

durable agents prompt creates a new interactive run and streams by default. For scripts, use --json, --no-stream, --wait, and --timeout when you need structured or bounded output.

Agent Skills

The README intentionally stays compact. The canonical task guides live in the Graphlit skills repo:

| Skill | Use it for | | --- | --- | | durable-cli | Installing, authenticating, scripting, connecting accounts, creating data sources, operating agents/runs, using Library/VFS commands, channels, email, messaging, and MCP connectors. | | durable-cli quickstart | The fastest path from install to a working Durable Agents session. | | durable-cli command surface | Choosing the right command family and avoiding naming mistakes such as accounts vs sources vs connectors vs channels. | | graphlit | Building Graphlit-powered apps with ingestion, retrieval, collections, sources, specifications, knowledge graph workflows, and streamAgent(). | | graphlit-agent-tools | 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

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

durable agents list
durable agents create --name "Research Assistant"
durable agents get <agent>
durable agents prompt <agent> "Summarize recent planning notes."

durable runs list --agent <agent>
durable runs get <run-id>
durable runs view <run-id>
durable runs view <run-id> --transcript
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>

Use agents schedule to turn an existing agent into an autonomous scheduled agent in one operation:

durable agents schedule <agent> \
  --cron "0 7 * * 1-5" \
  --timezone America/Los_Angeles \
  --prompt "Run the daily account sweep."

durable agents schedule <agent> \
  --cron "0 7 * * 1-5" \
  --prompt-file ./prompt.md

durable agents unschedule <agent>

Agent edits also support lower-level property grammar. For scheduled, triggered, heartbeat, and webhook agents, prompt is the stored execution instruction:

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

Interactive agents are promptless unless you explicitly set agent instructions. Automation agents receive a generic execution prompt when created without --prompt; pass --prompt or --prompt-file when you already know the job they should perform.

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

durable library list
durable library list --date-mode added --in-last 7d
durable library list --source "Work Calendar" --kind event
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" --source "Work Gmail"
durable library search "expansion risk" --search-type vector
durable library wait --source "Work Calendar" --kind event --query "Northwind Q2 QBR" --timeout 10m
durable library inspect <content-id>
durable library view <content-id>

durable fs ls /library
durable fs ls /library/contents --long
durable fs ls /library/labels/docs --long
durable fs find /library/kind/document --date-mode authored --in-last 30d --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. library search and library wait --query default to hybrid search; pass --search-type keyword|vector|hybrid when you need a specific mode. Use --min-relevance <score> on search or wait only when you want an explicit hybrid/vector relevance cutoff. Use durable library wait after async source creation when a script or demo needs matching content to be visible before prompting an agent. Use durable fs ... to navigate and search the derived /library filesystem view. /library is the navigation root; /library/contents lists all content. Content listings are newest by date added by default. Add --in-last <duration> with --date-mode added|authored to filter by date added or date authored.

Source Accounts And Data Sources

durable accounts connect github
durable accounts connect google --enable read
durable accounts connect google --enable read,write
durable accounts list
durable accounts get <account>
durable accounts reconnect <account> --enable read,write

durable sources create web --name "OpenAI Changelog" \
  --url "https://developers.openai.com/api/docs/changelog" --schedule 1day
durable sources create rss --name "OpenAI News" \
  --url "https://openai.com/news/rss.xml" --schedule 1day
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. accounts connect defaults to read access; pass --enable read,write when the account should also support action/write tools such as sending mail, writing calendar events, or creating documents. Use sources for the synced external content Durable should ingest. Use connectors only for MCP servers. For GitHub, accounts connect github opens the GitHub authorization and Durable Agents GitHub App install/configure flow. The GitHub App repository selection controls private and organization repository access; use durable accounts get <account> when troubleshooting account and app installation state. GitHub sources accept either --repo owner/repo or --repo https://github.com/owner/repo; discovery is useful for browsing but is not required when the repository is already known. For history-capable sources such as Gmail, Slack, calendars, and CRM providers, sources create prepares the historical import source plus a new-data monitoring sidecar automatically. The underlying sources remain visible in sources list and can be edited or deleted separately.

MCP Connectors And Channels

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 [email protected] --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:

durable --json agents list
durable --quiet runs watch <run-id>
durable --verbose status
durable --debug status

Capture IDs with --json for reliable automation:

AGENT_ID="$(durable --json agents create --name "Scripted Agent" | jq -r '.id')"
RUN_ID="$(durable --json agents prompt "$AGENT_ID" --no-stream "Reply READY only." | jq -r '.id')"

durable --json runs get "$RUN_ID"

Prompt text can be positional, read from --file, or piped through stdin:

durable agents prompt <agent> "Review this."
durable agents prompt <agent> --file ./prompt.md
cat ./prompt.md | durable agents prompt <agent>

Command Map

durable login | logout | whoami | status
durable auth import | export
durable keys list | create | revoke
durable usage
durable wallet fund | wallet fund status
durable models list

durable agents list | create | get | set | clear | prompt | update | delete
durable runs list | get | view | 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 | view | update | delete | search | wait
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:

durable agents prompt --help
durable sources create --help
durable channels bind --help
durable fs sgrep --help

Development

This package is built from apps/durable-cli.

npm run generate
npm run build
npm run check

For local API development:

export DURABLE_API_BASE_URL="http://localhost:3000"