Quickstart

From zero to querying your data in under a minute.

1. Sign up

Create an account at cograph.cloud/sign-up. Each account gets its own isolated knowledge graph tenant — your data is never mixed with anyone else's.

2. Install the CLI

bash

npm install -g cograph

Requires Node 20+. Or run on demand without installing: npx cograph ….

3. Sign in

bash

cograph login

Opens your browser, signs you in, and saves an API key to ~/.cograph/config.json (chmod 600). The CLI and SDK both read it automatically — no env vars needed for interactive use.

Headless / CI alternative: create a key in your dashboard and set COGRAPH_API_KEY. The env var wins over the config file when both are set.

4. Try the interactive shell

bash

cograph shell

A REPL with slash commands and live triple count:

text

    ░█▀▀░█▀█░█▀▀░█▀▄░█▀█░█▀█░█░█
    ░█░░░█░█░█░█░█▀▄░█▀█░█▀▀░█▀█
    ░▀▀▀░▀▀▀░▀▀▀░▀░▀░▀░▀░▀░░░▀░▀

    /ingest <file>      Ingest a CSV/JSON/text file
    /ask <question>     Ask in natural language
    /kg list            List your knowledge graphs
    /kg switch <name>   Switch active KG
    /kg create <name>   Create and switch to a new KG
    /types [query]      Types in this KG, with entity counts
    /type <name>        Drill into one type — attributes & relationships
    /enrich <Type> <attrs...>  Plan + run an enrichment job
    /enrich watch <job_id>     Live progress for a running job
    /enrich jobs               List recent jobs
    /enrich review <job_id>    Walk conflicts, accept/reject
    /login              Re-authenticate (browser)
    /status             Graph stats
    /reset              Clear the current KG
    /quit               Exit

  cograph ▸ /ingest sales.csv
  cograph [12,345] ▸ Which region has the highest average deal size?

Bare lines (no leading /) are auto-routed to /ask. Run /login from inside the shell to switch accounts or refresh a revoked key.

5. Browse what got ingested

After an ingest you usually want to look around before asking questions. /types lists every type in the active KG with its entity count; pass a substring to filter. /type <name> drills in to show attributes (with usage %), relationships to other types, and a few sample entities.

text

  cograph (mentors) [37,715] ▸ /types

    Type            Entities
    Mentor               988
    Skill                412
    Industry              38
    Discipline            17

  cograph (mentors) [37,715] ▸ /type Mentor

    Mentor  1,000 entities

    Attributes (6)
      .name           string      988  ( 99%)
      .level          string      714  ( 71%)
      ...

    Relationships (6)
      .title         → JobTitle    988  ( 99%) (+775 string)
      .skills        → Skill       987  ( 99%)
      .industries    → Industry    335  ( 34%)
      ...

    Sample entities
      1. Karthikeyan Rajasekaran
      2. Katie Duyen Nguyen
      3. Arjun Bali

Auto-attached system metadata (rdfs:label, ingested_at, source) is hidden by default — pass --system to see it. The (+775 string) annotation appears when the same column produced both a literal value and a typed-entity link during ingest.

6. Auto-enrichment

Sparse attributes? Point /enrich at a type and the columns you want filled — Cograph plans the job, queues it, and resolves missing values from the open web with citations and confidence scores. Conflicts are staged for review by default so the KG never gets dirty data silently.

text

  cograph (parts) [248,901] ▸ /enrich LineItem brand manufacturer

    Plan: enrich LineItem.brand, .manufacturer in parts
          tier: lite · policy: stage
    Job queued: enr_xxxxxxxx · 12,450 entities

    Watch progress? [Y/n] y
    [████████████████████] 12,450/12,450
      filled 6,200 · verified 1,400 · conflicts 320
    Status: review · 320 conflicts pending.
    Run /enrich review enr_xxxxxxxx

  cograph (parts) [248,901] ▸ /enrich review enr_xxxxxxxx

    LineItem #4471: "K&N 33-2304 air filter, red"
      brand: "KN" → "K&N"  (confidence 0.97, kn-filters.com)
    Accept? [a]/[r]/[s]/[A]ll/[q]uit:

/enrich watch re-attaches to a running job; /enrich jobs lists recent runs with their status. Nothing is written to the KG until you accept it under /enrich review — or pass an auto-apply policy when planning the job.

Self-hosted mode

Running your own Cograph server (OSS)? Skip the cloud login and point the CLI at your host:

bash

# Talk to a local server on http://localhost:8000
cograph --local

# Use COGRAPH_API_URL for any other host (no browser login)
cograph --no-login

# Or set the URL explicitly
COGRAPH_API_URL=http://your-host cograph

The shell prompt shows the host suffix when you're not on the managed cloud, so you always know where commands are landing — cograph@localhost:8000 (kg) ▸.

Or run one-shot commands

bash

cograph kg create my-dataset
cograph ingest your-data.csv --kg my-dataset
cograph ask "How many records are there?" --kg my-dataset

Each command is a single HTTP round-trip. Useful in scripts and CI. One LLM call infers the schema during ingest; all rows then map deterministically — no LLM per row.

From your code

import { Client } from "cograph";

// Reads ~/.cograph/config.json or COGRAPH_API_KEY automatically.
const client = new Client();

await client.ingest("sales.csv", { kg: "sales" });
const result = await client.ask(
  "What's the average deal size by region?",
  { kg: "sales" }
);
console.log(result.answer);

What happens under the hood

Ingestion: The CSV columns are analyzed by an LLM to determine which are attributes (numbers, dates, booleans) and which are relationships to other entities (cities, companies, categories). A typed ontology is created automatically. Each row becomes an entity with typed triples stored in the graph database.

Querying: Your natural language question is translated to SPARQL using the ontology as context. The query runs against the graph database and results are formatted as a human-readable answer.

Next steps

API Reference — the underlying REST API
MCP Server — connect Cograph to Claude, Cursor, or any MCP-compatible agent