Developing with agents: the CLI and your coding agent

• Install and configure the GraphN CLI
• Bootstrap Cursor, Claude Code, Codex, and AGENTS.md with project rules and optional MCP
• Use embedded skills and docs shipped with the CLI
• Follow a tight edit → validate → dry-run → publish loop

Command names: graphn workflow and graphn wf are the same command; graphn blueprint and graphn bp are the same command. Examples below use the long form.

1. Install the CLI

Homebrew (macOS / Linux)

brew tap voltagepark/graphn
brew install graphn

Direct download

curl -sSL https://github.com/voltagepark/graphn-cli/releases/latest/download/graphn-darwin-arm64 -o graphn && sudo install graphn /usr/local/bin/graphn && rm graphn

curl -sSL https://github.com/voltagepark/graphn-cli/releases/latest/download/graphn-darwin-amd64 -o graphn && sudo install graphn /usr/local/bin/graphn && rm graphn

curl -sSL https://github.com/voltagepark/graphn-cli/releases/latest/download/graphn-linux-amd64 -o graphn && sudo install graphn /usr/local/bin/graphn && rm graphn

curl -sSL https://github.com/voltagepark/graphn-cli/releases/latest/download/graphn-linux-arm64 -o graphn && sudo install graphn /usr/local/bin/graphn && rm graphn

Verify and update

graphn version
graphn --help

graphn update

2. Authenticate

Browser login (recommended)

graphn login

Or: API key

1. In the GraphN web app, open your workspace Settings → API Keys (or click the API Keys button in the header) and create a key.
2. Run the interactive setup:
   bash

   graphn init --setup-only

   This stores your API base URL (for production, typically https://cp.graphn.ai), API key, and default workspace ID in the CLI config.

Verify connectivity

graphn whoami
graphn config show

3. Bootstrap your repo for AI assistants (graphn init)

Codex trust prompt: because .codex/config.toml is project-scoped rather than global, Codex only loads it for directories you have trusted and prompts the first time you run codex in the project. Until you accept, the GraphN MCP server will not appear under /mcp.

Choosing agents

graphn init                      # Cursor + Claude Code, plus any agent detected here
graphn init --agent codex        # one agent
graphn init --agent cursor,codex # several (repeatable or comma-separated)
graphn init --agent all          # every supported agent
graphn init --agent auto         # only agents this directory shows evidence of

• --setup-only — only API/workspace setup; no rule files.
• --skills-only — only create/update rule files; no setup wizard.
• --cursor-only / --claude-only — deprecated aliases for --agent cursor / --agent claude. They still work, but cannot be combined with --agent.

4. Embedded skills and documentation (graphn docs)

graphn docs skills                    # list available skills
graphn docs skills workflow-building  # patterns, deploy checklist, secrets
graphn docs skills rag-pipeline       # RAG / knowledge-base workflows
graphn docs skills debugging          # failure diagnosis, common errors
graphn docs skills gateway-modes      # sync vs async, --gateways flag, polling
graphn docs skills dsl-schema         # full DSL schema
graphn docs skills dsl-commands       # CLI command reference

graphn docs dsl
graphn docs api
graphn docs helpers
graphn docs all

5. Expose the CLI to the IDE via MCP (graphn mcp-serve)

graphn mcp-serve

{
  "mcpServers": {
    "graphn": {
      "command": "graphn",
      "args": ["mcp-serve"]
    }
  }
}

{
  "mcpServers": {
    "graphn": {
      "command": "graphn",
      "args": ["mcp-serve"]
    }
  }
}

[mcp_servers.graphn]
command = "graphn"
args = ["mcp-serve"]

6. A practical development loop

1. Inspect workspace state
   bash

   graphn context
   graphn workflow list

2. Edit — In the UI, or locally: export a bundle or DSL if your team uses repo-backed YAML, then push changes to the API:
   bash

   graphn workflow update <workflow-id-or-name> --dsl ./workflow.yaml

   Use the workflow name or ID (wf_…) from graphn workflow list.
   The template YAML tab in the web app is the same DSL you can validate and update from disk:

   

   For a full DSL reference, see Workflow DSL.
3. Validate
   bash

   graphn workflow validate ./workflow.yaml
   graphn workflow validate ./workflow.yaml --deep

4. Test without the gateway
   bash

   graphn workflow dry-run <workflow-id-or-name> --input-file ./input.json

5. Publish components so production runs resolve pinned versions:
   bash

   graphn agent publish "<Agent Name>"
   graphn workflow publish <workflow-id-or-name> -m "Describe change"

6. Production run (requires gateway URL):
   bash

   graphn config set-gateway-url https://your-gateway-base
   graphn workflow run <workflow-id-or-name> --input-file ./input.json

7. Blueprints from the CLI

graphn blueprint list
graphn blueprint info kb-ingestion
graphn blueprint deploy kb-ingestion --name "My Company KB Search"

8. When you need more than the default templates

• Extend MCP tools (e.g. keyword search, document listing, bounded full-text read) where the product supports them.
• Rewrite Researcher and Synthesizer instructions for your output schema (tables, columns, evidence quotes).
• Run dry-runs on real contracts and iterate until stakeholders sign off.

9. Telemetry

• Command name, error messages, and CLI arguments
• Workspace ID, org ID, and API URL
• Request bodies (for debugging failed API calls)
• CLI version, OS, and architecture
• Anonymous device ID (random UUID, not tied to your account)

# Disable permanently
graphn telemetry disable

# Disable for a single session
GRAPHN_TELEMETRY_DISABLED=1 graphn <command>

# Re-enable
graphn telemetry enable

# Check current status
graphn telemetry status

10. Related documentation

• Getting started — first workflow in the browser
• Core concepts — workspaces, workflows, agents
• Workflow DSL — YAML reference
• API reference — HTTP API for automation
• Document analysis tutorial — structured extraction from documents

11. Troubleshooting