Proxy CLI Reference

The agentcy-proxy-cli is a production-grade CLI for interacting with the Agentcy knowledge graph and file storage from pipelines, sandboxes, or local development. It provides a direct interface to graph operations, file management, and pipeline progress reporting without requiring the web UI.

When to use it:

Ingesting codebases into the knowledge graph from CI/CD pipelines
Batch graph operations (bulk node/relationship creation, Cypher queries)
Pipeline agent communication (logging, progress tracking)
Local development and scripting against the Agentcy API
Claude Code integration via the /graph-proxy skill

Installation

One-liner (from your Agentcy server)Make targetsCargo (from source)

bash

curl -fsSL http://your-server/api/v1/cli/install.sh | bash

bash

# Build the binary
make proxy-cli

# Build and install to /usr/local/bin
make proxy-cli-install

bash

cd backend && cargo build --release -p agentcy-proxy-cli
cp target/release/agentcy-proxy-cli /usr/local/bin/

Verify the installation:

bash

agentcy-proxy-cli --version

Configuration

The CLI reads configuration from environment variables.

Variable	Required	Description
`AGENTCY_API_URL`	Yes	Base URL of the Agentcy API (e.g., `http://localhost:18080/api/v1`)
`AGENTCY_TOKEN`	Yes	Pipeline-scoped JWT token
`PIPELINE_ID`	No	Pipeline UUID (informational, used for log/progress tracking)

Quick Setup

Use the setup script to configure all variables at once:

bash

eval $(./scripts/proxy-cli-setup.sh)

Or set them manually:

bash

export AGENTCY_API_URL=http://localhost:18080/api/v1
export AGENTCY_TOKEN=$(curl -s http://localhost:18080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@localhost","password":"admin"}' | jq -r .token)

TIP

The ingest scan command works locally without API connectivity. All other commands require AGENTCY_API_URL and AGENTCY_TOKEN to be set.

Global Options

Flag	Short	Description
`--json`	`-j`	Output raw JSON (for piping and parsing)
`--quiet`	`-q`	Suppress informational messages, only output data
`--verbose`	`-v`	Show request/response details for debugging

These flags can be used with any command:

bash

# JSON output for scripting
agentcy-proxy-cli --json graph stats

# Quiet mode for automation
agentcy-proxy-cli -q graph add-node --label Person --key alice --prop name=Alice

# Verbose mode for debugging
agentcy-proxy-cli -v status

Graph Commands

Knowledge graph operations: create nodes and relationships, search, query, and manage graph data.

`graph write-nodes`

Write multiple nodes from a JSON file, inline data, or stdin.

Flag	Description
`--file <path>`	Path to a JSON file containing an array of node objects
`--data <json>`	Inline JSON array of node objects
`--stdin`	Read JSON from stdin

Exactly one of --file, --data, or --stdin is required.

bash

# From a file
agentcy-proxy-cli graph write-nodes --file nodes.json

# Inline data
agentcy-proxy-cli graph write-nodes --data '[
  {"label": "Person", "properties": {"_key": "alice", "name": "Alice", "role": "engineer"}},
  {"label": "Person", "properties": {"_key": "bob", "name": "Bob", "role": "designer"}}
]'

# From stdin (pipe from another command)
cat nodes.json | agentcy-proxy-cli graph write-nodes --stdin

`graph add-node`

Add a single node inline without needing a JSON file.

Flag	Description
`--label <label>`	Node label (e.g., `Person`, `Company`, `Service`)
`--key <key>`	Node key (stored as the `_key` property)
`--prop <KEY=VALUE>`	Property as key=value pair (repeatable)

bash

agentcy-proxy-cli graph add-node \
  --label Person \
  --key alice \
  --prop name=Alice \
  --prop role=engineer \
  --prop active=true

TIP

Property values are automatically parsed as booleans (true/false), integers, floats, or strings.

`graph write-rels`

Write multiple relationships from a JSON file, inline data, or stdin.

Flag	Description
`--file <path>`	Path to a JSON file containing an array of relationship objects
`--data <json>`	Inline JSON array of relationship objects
`--stdin`	Read JSON from stdin

bash

# From a file
agentcy-proxy-cli graph write-rels --file relationships.json

# Inline data
agentcy-proxy-cli graph write-rels --data '[
  {"type": "WORKS_AT", "from_label": "Person", "from_key": "alice", "to_label": "Company", "to_key": "acme"}
]'

`graph add-rel`

Add a single relationship inline.

Flag	Description
`--type <type>`	Relationship type (e.g., `WORKS_AT`, `MANAGES`, `DEPENDS_ON`)
`--from <Label:key>`	Source node reference (e.g., `Person:alice`)
`--to <Label:key>`	Target node reference (e.g., `Company:acme`)
`--prop <KEY=VALUE>`	Property as key=value pair (repeatable)

bash

agentcy-proxy-cli graph add-rel \
  --type WORKS_AT \
  --from Person:alice \
  --to Company:acme \
  --prop since=2024 \
  --prop department=engineering

`graph search`

Search nodes by text query with optional label filtering.

Flag	Description
`--query <text>`	Search query string (required)
`--limit <n>`	Maximum number of results (default: `20`)
`--label <label>`	Filter by label (repeatable for multiple labels)

bash

# Basic search
agentcy-proxy-cli graph search --query "authentication"

# Search with label filter
agentcy-proxy-cli graph search --query "login" --label Service --label Function

# JSON output with limit
agentcy-proxy-cli --json graph search --query "database" --limit 50

`graph get`

Get a node by its ID.

Flag	Description
`--id <id>`	Node ID (e.g., `Person:alice`)

bash

agentcy-proxy-cli graph get --id "Person:alice"

`graph delete`

Delete a node by its ID.

Flag	Description
`--id <id>`	Node ID (e.g., `Person:alice`)

bash

agentcy-proxy-cli graph delete --id "Person:alice"

WARNING

Deleting a node also removes all relationships connected to it.

`graph cypher`

Execute a raw Cypher query against the knowledge graph. The query is positional for convenience.

bash

# Count nodes by label
agentcy-proxy-cli graph cypher "MATCH (n) RETURN labels(n) AS label, count(*) AS count ORDER BY count DESC"

# Find connected components
agentcy-proxy-cli graph cypher "MATCH (a:Service)-[:DEPENDS_ON]->(b:Service) RETURN a.name, b.name LIMIT 20"

# JSON output for scripting
agentcy-proxy-cli --json graph cypher "MATCH (n:Person) RETURN n.name, n.role"

`graph stats`

Get graph statistics (total node count, relationship count, and optionally per-label breakdowns).

Flag	Description
`--labels`	Show per-label counts

bash

# Basic stats
agentcy-proxy-cli graph stats

# With per-label breakdown
agentcy-proxy-cli graph stats --labels

Example output:

Graph Statistics
  Nodes:         12.4K
  Relationships: 38.7K
  Labels:
    Function             4,210
    File                 3,102
    Module               2,891
    Service              1,044
    ...

Files Commands

Pipeline artifact file operations: list, upload, download, and inspect files stored in the Agentcy workspace.

`files list`

List pipeline artifact files with optional filtering and sorting.

Flag	Description
`--filter <glob>`	Filter files by glob pattern (e.g., `.csv`, `output/`)
`--sort <field>`	Sort by: `name`, `size`, `modified` (default: `name`)
`--desc`	Sort descending

bash

# List all files
agentcy-proxy-cli files list

# Filter and sort
agentcy-proxy-cli files list --filter "*.json" --sort size --desc

`files download`

Download a pipeline artifact file.

Flag	Description
`--path <remote>`	Remote file path (e.g., `output/results.json`)
`--output <local>`	Local output file path (defaults to current dir with same filename)

bash

# Download to current directory
agentcy-proxy-cli files download --path output/results.json

# Download to a specific path
agentcy-proxy-cli files download --path output/results.json --output /tmp/results.json

`files upload`

Upload a single file as a pipeline artifact.

Flag	Description
`--input <local>`	Local file path to upload
`--path <remote>`	Remote path to store the file at

bash

agentcy-proxy-cli files upload --input ./report.csv --path output/report.csv

`files upload-dir`

Upload an entire directory recursively.

Flag	Description
`--input <dir>`	Local directory to upload
`--prefix <prefix>`	Remote path prefix (default: empty)

bash

# Upload a build output directory
agentcy-proxy-cli files upload-dir --input ./dist --prefix builds/v1.2.3

# Upload with verbose progress
agentcy-proxy-cli -v files upload-dir --input ./data --prefix datasets/

`files info`

Get file metadata (size, type, modification time).

Flag	Description
`--path <remote>`	Remote file path

bash

agentcy-proxy-cli files info --path output/results.json

Ingest Commands

Scan and upload local directories, with include/exclude filtering by glob patterns.

`ingest scan`

Scan a local directory and report file statistics. This command runs locally and does not require API connectivity.

Flag	Description
`--dir <path>`	Directory to scan (required)
`--include <glob>`	Include only files matching this pattern (repeatable)
`--exclude <glob>`	Exclude files/directories matching this pattern (repeatable)
`--dry-run`	Only show what would be processed

bash

# Scan a Rust project
agentcy-proxy-cli ingest scan --dir ./backend \
  --include "*.rs" --include "*.toml" \
  --exclude target --exclude .git

# Scan with JSON output for scripting
agentcy-proxy-cli --json ingest scan --dir ./src

Example output:

Scan: ./backend (include: *.rs, *.toml; exclude: target, .git)

  Found 247 files (1.2 MB total)

  Type                 Count  Size
  .rs                  198    982.4 KB
  .toml                49     218.1 KB

`ingest upload`

Upload matching files from a local directory to the Agentcy file store.

Flag	Description
`--dir <path>`	Directory to upload from (required)
`--include <glob>`	Include only files matching this pattern (repeatable)
`--exclude <glob>`	Exclude files/directories matching this pattern (repeatable)
`--prefix <prefix>`	Remote path prefix (default: empty)

bash

# Upload source files
agentcy-proxy-cli ingest upload --dir ./src \
  --exclude node_modules --exclude .git \
  --prefix "project/src"

Pipeline Commands

Log messages and report progress for pipeline tracking.

`log`

Log a message for the current pipeline. The message is positional for convenience.

Flag	Description
`--level <level>`	Log level: `debug`, `info`, `warn`, `error`, `agent`, `graph` (default: `info`)
`--phase <name>`	Pipeline phase name

bash

# Simple log
agentcy-proxy-cli log "Starting codebase ingestion"

# With level and phase
agentcy-proxy-cli log "Found 3 critical vulnerabilities" --level warn --phase security-scan

# Agent-level log
agentcy-proxy-cli log "Analyzing dependency graph" --level agent --phase analysis

`progress`

Report progress for the current pipeline. The percentage (0.0-1.0) is positional, with an optional message.

Flag	Description
`--phase <name>`	Pipeline phase name

bash

# Report 50% progress
agentcy-proxy-cli progress 0.5

# With a message
agentcy-proxy-cli progress 0.75 "Processing relationships"

# With phase
agentcy-proxy-cli progress 1.0 "Complete" --phase ingestion

Status

Check API connectivity and display graph statistics.

bash

agentcy-proxy-cli status

Example output:

Connected to http://localhost:18080/api/v1
  Graph: 12.4K nodes, 38.7K relationships

Use --json for machine-readable output:

bash

agentcy-proxy-cli --json status

json

{
  "connected": true,
  "api_url": "http://localhost:18080/api/v1",
  "graph_stats": {
    "node_count": 12400,
    "relationship_count": 38700
  }
}

JSON Formats

Node Object

Nodes require a label and a properties map. The _key property is used as the unique identifier within that label.

json

{
  "label": "Service",
  "properties": {
    "_key": "auth-api",
    "name": "Auth API",
    "language": "rust",
    "port": 8080,
    "healthy": true
  }
}

Relationship Object

Relationships reference source and target nodes by label and key.

json

{
  "type": "DEPENDS_ON",
  "from_label": "Service",
  "from_key": "auth-api",
  "to_label": "Service",
  "to_key": "user-db",
  "properties": {
    "protocol": "postgres",
    "required": true
  }
}

Use Cases

1. Ingest a Codebase

Full workflow for ingesting a codebase into the knowledge graph:

bash

# 1. Configure the CLI
export AGENTCY_API_URL=http://localhost:18080/api/v1
export AGENTCY_TOKEN=your-jwt-token

# 2. Scan the codebase to see what will be ingested
agentcy-proxy-cli ingest scan --dir ./my-project \
  --exclude node_modules --exclude .git --exclude target

# 3. Upload files to Agentcy storage
agentcy-proxy-cli ingest upload --dir ./my-project \
  --exclude node_modules --exclude .git --exclude target \
  --prefix "my-project"

# 4. Create graph nodes for key components
agentcy-proxy-cli graph add-node --label Repository --key my-project \
  --prop name=my-project --prop language=typescript

agentcy-proxy-cli graph add-node --label Service --key api-server \
  --prop name="API Server" --prop port=3000

# 5. Add relationships
agentcy-proxy-cli graph add-rel \
  --type CONTAINS \
  --from Repository:my-project \
  --to Service:api-server

# 6. Verify
agentcy-proxy-cli graph stats --labels

2. Batch Create from Script

Use shell scripting for bulk operations:

bash

#!/bin/bash
set -euo pipefail

# Read a CSV and create nodes
while IFS=, read -r name role department; do
  agentcy-proxy-cli -q graph add-node \
    --label Employee \
    --key "$name" \
    --prop name="$name" \
    --prop role="$role" \
    --prop department="$department"
done < employees.csv

echo "Done. Graph stats:"
agentcy-proxy-cli graph stats --labels

Or generate JSON for bulk writes:

bash

# Generate nodes from a tool and pipe via stdin
my-analyzer --output-json | agentcy-proxy-cli graph write-nodes --stdin

3. Claude Code Integration

The proxy CLI integrates with Claude Code via the /graph-proxy skill, allowing Claude Code to read from and write to the Agentcy knowledge graph during coding sessions.

The install script (install.sh) auto-creates the Claude Code skill configuration. For manual setup:

Ensure agentcy-proxy-cli is on your PATH
Set the environment variables (AGENTCY_API_URL, AGENTCY_TOKEN)
The skill commands map directly to CLI subcommands

4. Pipeline Agent

Inside CIAB sandboxes and CI/CD pipelines, the proxy CLI acts as the communication channel between the agent and Agentcy:

bash

#!/bin/bash
# Pipeline agent script

agentcy-proxy-cli log "Pipeline started" --phase init
agentcy-proxy-cli progress 0.0 "Starting" --phase init

# Phase 1: Scan
agentcy-proxy-cli progress 0.1 "Scanning codebase" --phase scan
agentcy-proxy-cli ingest upload --dir /workspace/src --prefix "pipeline/src"
agentcy-proxy-cli progress 0.3 "Scan complete" --phase scan

# Phase 2: Analyze
agentcy-proxy-cli progress 0.4 "Analyzing dependencies" --phase analyze
agentcy-proxy-cli graph write-nodes --file /tmp/analysis-nodes.json
agentcy-proxy-cli graph write-rels --file /tmp/analysis-rels.json
agentcy-proxy-cli progress 0.8 "Analysis complete" --phase analyze

# Phase 3: Report
agentcy-proxy-cli progress 0.9 "Generating report" --phase report
agentcy-proxy-cli files upload --input /tmp/report.html --path "reports/latest.html"
agentcy-proxy-cli log "Pipeline complete" --level info --phase report
agentcy-proxy-cli progress 1.0 "Done" --phase report

Troubleshooting

Error	Cause	Fix
`AGENTCY_API_URL not set`	Missing environment variable	Run `eval $(./scripts/proxy-cli-setup.sh)` or export manually
`AGENTCY_TOKEN not set`	Missing JWT token	Obtain a token via `/api/v1/auth/login`
`Cannot connect to ...`	API server unreachable	Check `AGENTCY_API_URL` and that the backend is running
`401 Unauthorized`	Expired or invalid JWT	Re-authenticate to get a fresh token
`One of --file, --data, or --stdin is required`	No input source specified	Provide exactly one of the three input flags
`Invalid node reference`	Malformed `Label:key` string	Use the format `Label:key` (e.g., `Person:alice`)
`Invalid filter pattern`	Bad glob syntax in `--filter`	Check your glob pattern syntax

Proxy CLI Reference ​

Installation ​

Configuration ​

Quick Setup ​

Global Options ​

Graph Commands ​

graph write-nodes ​

graph add-node ​

graph write-rels ​

graph add-rel ​

graph search ​

graph get ​

graph delete ​

graph cypher ​

graph stats ​

Files Commands ​

files list ​

files download ​

files upload ​

files upload-dir ​

files info ​

Ingest Commands ​

ingest scan ​

ingest upload ​

Pipeline Commands ​

log ​

progress ​

Status ​

JSON Formats ​

Node Object ​

Relationship Object ​

Use Cases ​

1. Ingest a Codebase ​

2. Batch Create from Script ​

3. Claude Code Integration ​

4. Pipeline Agent ​

Troubleshooting ​

Proxy CLI Reference

Installation

Configuration

Quick Setup

Global Options

Graph Commands

`graph write-nodes`

`graph add-node`

`graph write-rels`

`graph add-rel`

`graph search`

`graph get`

`graph delete`

`graph cypher`

`graph stats`

Files Commands

`files list`

`files download`

`files upload`

`files upload-dir`

`files info`

Ingest Commands

`ingest scan`

`ingest upload`

Pipeline Commands

`log`

`progress`

Status

JSON Formats

Node Object

Relationship Object

Use Cases

1. Ingest a Codebase

2. Batch Create from Script

3. Claude Code Integration

4. Pipeline Agent

Troubleshooting