Anything CLI documentation

2. Install and run

The recommended path is the npm CLI — it clones anything-cli to ~/.anythinggraph/source, builds the Rust reasoning service, and starts MCP on port 3334. You do not need to manually run cargo build for a normal install.

Option A — npm CLI (recommended)

Requirements: Node.js 18+, git, and Rust cargo (used once during onboard to compile reasoning-service).

npm install -g @anythinggraph/cli@latest
anythinggraph onboard --install-daemon
anythinggraph start

What this does:

• onboard — clones or updates the repo under ~/.anythinggraph/source and builds binaries into ~/.anythinggraph/bin/
• --install-daemon — optional macOS launchd / Linux systemd user service so services restart on login
• start — runs the same stack as ./start-all.sh (reasoning API + MCP HTTP)

After onboard, add your data source credentials:

cp ~/.anythinggraph/source/.env.example ~/.anythinggraph/source/.env
# edit AG_SQL_DSN, AG_MONGODB_DSN, AG_SF_ACCESS_TOKEN, etc.

anythinggraph start loads .env from the checkout automatically. Use anythinggraph start --rebuild-rust after pulling Rust changes.

Useful CLI commands:

Bootstrap without npm (alternative):

curl -fsSL https://raw.githubusercontent.com/AnythingGraph/anything-cli/main/cli/install.sh | bash

Option B — clone from source (contributors)

For local development or contributing to the repo:

git clone https://github.com/AnythingGraph/anything-cli.git
cd anything-cli

cp .env.example .env
# edit .env with your connection strings

chmod +x start-all.sh
./start-all.sh

start-all.sh stops any existing processes on ports 8787 and 3334, loads .env when present, sets AG_AUTH_DISABLED=1 for local dev, and starts both services. Press Ctrl+C to stop.

Manual build (only if you are hacking on Rust without the npm CLI):

cargo build --release
cd mcp && npm install && cd ..

Services

Credentials live in .env (gitignored). Named connections are registered in profiles/local.yaml using env:AG_* references — never put secrets in playbooks or bindings. See Profiles and .env.example in the repo for all variables.

Demo-only environment variables (use what matches your setup):

# Postgres — profile key warehouse_pg
AG_SQL_DSN=postgres://user:pass@localhost:5432/yourdb

# Payroll CSV demo — profile key payroll_csv
AG_PAYROLL_CSV_PATH=./data/payroll.csv

# MongoDB — profile key mongo_main
AG_MONGODB_DSN=mongodb://localhost:27017
AG_MONGODB_DATABASE=mydb

# Salesforce — profile key salesforce_main
AG_SF_INSTANCE_URL=https://your-org.my.salesforce.com
AG_SF_ACCESS_TOKEN=your_access_token

Sample Postgres schema for CRM demo playbooks (simple-crm-access, crm-payroll-access):

CREATE TABLE users (
  user_id   TEXT PRIMARY KEY,
  full_name TEXT NOT NULL
);

CREATE TABLE accounts (
  account_name  TEXT PRIMARY KEY,
  industry      TEXT,
  owner_user_id TEXT NOT NULL REFERENCES users(user_id)
);

INSERT INTO users VALUES ('alex.ae', 'Alex Anderson');
INSERT INTO accounts VALUES
  ('Northwind Traders', 'Retail', 'alex.ae'),
  ('Contoso Ltd', 'Technology', 'alex.ae');

Payroll sample data: data/payroll.csv (column user links to users.user_id).

Validate playbooks from a source checkout:

cargo run -p anythinggraph-ag -- validate --playbooks playbooks

3. Core concepts

Anything CLI separates what you mean from where data lives and who may see it.

Not moving your data means:

• No ETL pipeline required to “feed” the agent.
• Each query runs at the source via the adapter (SQL, SOQL, file read).
• Federated playbooks can touch Postgres and CSV in one user question — still no copy step.

Query flow:

1. Agent calls query_graph with a playbook id and a question shape (resolve user, count relationship, …).
2. Runtime compiles a plan from the playbook.
3. Runtime picks the binding from entity_sources + bindings.
4. Adapter executes at the source; optional ReBAC filters results.
5. Proof envelope returns counts, rows, and evidence.

4. What is a playbook?

A playbook (playbooks/<id>.json) is a portable description of a use case in your domain — who may see what, and how concepts connect. The repo ships demo playbooks; you author new ones for your business.

Step-by-step guide: create a playbook and binding →

Demo playbooks included in the repo (not prescriptive — copy and adapt):

• simple-crm-access — Postgres CRM (user → owned accounts)
• crm-payroll-access — Postgres CRM + payroll CSV (federated)
• salesforce-lead-access — Salesforce User + Lead

Example JSON

// Demo playbook shape — crm-payroll-access (illustrative only)
{
  "id": "crm-payroll-access",
  "entities": [ { "name": "crm_user", "fields": [...] }, ... ],
  "entity_relationships": [
    { "relationship_name": "owns_account", "subject_entity_name": "crm_user", "object_entity_name": "crm_account" }
  ],
  "entity_sources": {
    "crm_user": "postgres",
    "crm_account": "postgres",
    "crm_payroll_record": "csv"
  },
  "bindings": {
    "postgres": "crm-payroll-access.postgres",
    "csv": "crm-payroll-access.csv"
  }
}

5. What is a binding?

A binding (bindings/<playbook_id>.<source>.yaml) connects playbook vocabulary to physical storage for one source. One playbook often has multiple binding files. See the playbooks & bindings guide for Postgres, CSV, and Salesforce examples.

Example YAML (compact format)

# bindings/crm-payroll-access.postgres.yaml
source_id: warehouse_pg

entities:
  crm_user:
    from: users
    id: user_id
    fields: [full_name]

  crm_account:
    from: accounts
    id: account_name
    fields: [industry]

relationships:
  owns_account:
    object: crm_account
    link_column: owner_user_id

• source_id — profile source key (credentials live in profiles/local.yaml)
• from — table, file, or Salesforce object name
• id — primary identifier column for the entity
• fields — playbook field names, or playbook_field: column when names differ
• relationships.*.object + link_column — object-side column linking back to the subject id

You usually do not write SQL by hand. With from, id, fields, and link_column, the runtime compiles lookup, count, list, and ReBAC list_all queries at load time. When saving via MCP, save_binding writes your compact YAML verbatim — it does not expand to legacy lookup / operations blocks on disk.

6. Profiles

Profiles (profiles/local.yaml) register named sources. Bindings reference them via source_id. Credentials never go in playbooks or bindings.

Connect your data sources → Step-by-step guide for local.yaml, .env, and MySQL, Salesforce, CSV, and MongoDB.

Example profile

# Demo sources — rename keys and env vars for your environment
sources:
  warehouse_pg:
    adapter: sql
    dsn: env:AG_SQL_DSN
  mysql_main:
    adapter: mysql
    dsn: env:AG_MYSQL_DSN
  mssql_main:
    adapter: mssql
    dsn: env:AG_MSSQL_DSN
  mongodb_main:
    adapter: mongodb
    dsn: env:AG_MONGODB_URI
    database: env:AG_MONGODB_DATABASE
  rest_api:
    adapter: rest
    base_url: env:AG_REST_BASE_URL
    auth: env:AG_REST_TOKEN
  payroll_csv:
    adapter: csv
    file_path: env:AG_PAYROLL_CSV_PATH
  salesforce_main:
    adapter: soql
    instance_url: env:AG_SF_INSTANCE_URL
    auth: env:AG_SF_ACCESS_TOKEN

Values prefixed with env: are resolved from environment variables at startup. Override the profile path with AG_PROFILE_PATH.

7. Data adapters

Adapters implement a common interface: execute plan steps and load entity rows for ReBAC graph materialization. Each profile entry sets adapter: to pick the implementation. Seven adapters ship today; more are on the roadmap — same playbook model, different backends.

Binding patterns for newer adapters:

• mysql / mssql — same YAML shape as Postgres (from, fields, subject_link_column); SQL dialect is compiled automatically
• mongodb — set from to a collection name; runtime compiles find: / count: operations
• rest — set from to an API path (e.g. /users); runtime compiles GET request templates; profile needs base_url

Binding file suffix often matches the source key (.postgres, .mysql, .mongodb, .rest, …). The adapter type comes from the profile entry referenced by source_id.

8. Ontology — entities and relationships

The ontology inside a playbook is the shared language agents and humans use — independent of table or column names.

Entities are things in your world — you choose the names. Demo playbooks use names like:

• crm_user — example fields user_id, full_name
• crm_account — example fields account_name, industry
• crm_payroll_record, crm_lead — other demo entities

Relationships are directed edges you define between entities. Demo examples:

• owns_account — example: crm_user → crm_account
• user_has_payroll — example: crm_user → crm_payroll_record
• assigned_to — example: crm_user → crm_lead

Playbook relationships are logical. Bindings supply the physical join in your systems (foreign keys, owner columns, file columns, …). The demo uses names like owner_user_id and OwnerId — yours will differ.

9. ReBAC — relationship-based access control

When relationship_access_rules.active is true, Anything CLI enforces relationship-based access control (ReBAC) at query time. Access follows graph paths — e.g. “a person may read records linked via a relationship you define” — not just a static role flag.

Example rule block (demo playbook)

// relationship_access_rules — illustrative; use your entity and relationship names
"relationship_access_rules": {
  "subject_entity_name": "crm_user",
  "subject_identifier_field": "user_id",
  "deny_by_default": true,
  "active": true,
  "rules": [
    {
      "id": "own_accounts",
      "effect": "allow",
      "resource_entity_name": "crm_account",
      "path": [
        {
          "relationship_name": "owns_account",
          "direction": "forward",
          "from_entity_name": "crm_user",
          "to_entity_name": "crm_account"
        }
      ]
    }
  ]
}

How it works:

1. Rules define allow paths over playbook relationships.
2. At runtime, a federated graph is materialized from bindings (list_all per entity).
3. Count/list queries filter to rows the subject may access.
4. Proof includes rebac_applied: true when enforcement ran.

MCP tool list_allowed_rows returns visible row ids per entity for a subject — useful for debugging access.

10. Setup and use via MCP

The MCP server (http://127.0.0.1:3334/mcp) is a thin bridge to the Rust reasoning service (http://127.0.0.1:8787). Agents call MCP tools; MCP forwards to the reasoning API with your bearer token. See Auth & roles for token setup.

Connect in Cursor

1. Run anythinggraph start (npm CLI) or ./start-all.sh from a source checkout. Set auth env vars in .env if enabled.
2. In Cursor → Settings → MCP, add server URL: http://127.0.0.1:3334/mcp
3. When auth is enabled, add header Authorization: Bearer <your-token> (admin for authoring, user for query-only).
4. Or run anythinggraph mcp print-config and paste the JSON snippet.

Cursor MCP config (HTTP + auth)

{
  "mcpServers": {
    "anythinggraph-thin": {
      "url": "http://127.0.0.1:3334/mcp",
      "headers": {
        "Authorization": "Bearer admin-secret-change-me"
      }
    }
  }
}

Ask questions (user role)

Replace the playbook id and names with yours. Prompts below use the demo playbook crm-payroll-access:

// Demo prompts — swap playbook id and person name for yours
For playbook crm-payroll-access: how many accounts does Alex Anderson own?

For playbook <your-playbook-id>: how many <relationship> records does <person> have?

Typical user flow: list_playbooks → get_playbook_context → query_graph.

Author playbooks & bindings (admin role)

Admin agents create or update artifacts on disk. Use compact declarative format — see the MCP playbook authoring guide (tool sequence + visual flow), the playbooks guide, and repo AGENTS.md.

1. list_sources — see configured profile sources (credentials are not exposed)
2. introspect_source — read schema only (Postgres tables, CSV columns, Salesforce objects)
3. propose_playbook → save_playbook — validate then write playbooks/{id}.json
4. get_playbook_context → suggest_bindings — entity → table hints
5. propose_binding → test_binding → save_binding — validate, try live query, save YAML verbatim

Using anythinggraph-thin MCP: load playbook <your-playbook-id>, inspect my data
source, suggest how to map entities to my tables, test the binding, and save it.

MCP tool reference

propose_binding returns a save_instruction telling agents to save the same compact YAML they submitted — not expanded SQL. Set AG_DEBUG_COMPILED=1 on the reasoning service only if you need debug_compiled_binding_yaml for troubleshooting.

11. Auth & roles

One MCP server and one reasoning API serve both everyday queries and admin authoring. Clients authenticate with a bearer token; the token maps to either a user or admin role. Tool lists and HTTP routes are filtered by role.

Environment variables

Set the same token lists on both the reasoning service and the MCP process:

export AG_ADMIN_TOKENS="admin-secret-change-me"
export AG_USER_TOKENS="user-secret-change-me"

Comma-separate multiple tokens per role if needed. When both variables are unset, auth is disabled (local development only).

Role capabilities

How clients send the token

• Cursor / HTTP MCP — add Authorization: Bearer <token> in MCP server headers (see section 10).
• Reasoning API direct — same header on requests to http://127.0.0.1:8787.
• Stdio MCP — set AG_MCP_AUTH_TOKEN to a token from AG_ADMIN_TOKENS or AG_USER_TOKENS.