Graphify Command-Line Arguments: Complete CLI Reference

Graphify exposes nine primary sub-commands through its dispatch interface in graphify/cli.py, enabling provider management, graph traversal, memory storage, and repository operations via specific flags and positional arguments.

The Graphify-Labs/graphify repository implements a powerful command-line interface centered in graphify/cli.py. Each sub-command registers its own argument parser with distinct options for customizing graph analysis workflows, from natural-language querying to provider registration and Git hook management.

Provider Management Commands

The provider Sub-Command

The provider sub-command manages custom LLM provider registrations. According to the source code in graphify/cli.py (lines 26-69), it supports four operations:

• list – Displays all registered custom providers
• show – Outputs a provider’s JSON definition
• add – Registers a new provider with configuration flags
• remove – Deletes a provider from the registry

The add operation requires three flags and accepts two optional pricing parameters:

graphify provider add <name> \
  --base-url <URL> \
  --default-model <MODEL> \
  --env-key <KEY> \
  [--pricing-input <N>] \
  [--pricing-output <N>]

Graph Traversal and Query Commands

The query Sub-Command

The query sub-command executes natural-language searches against the knowledge graph. Implemented around lines 64-80 in graphify/cli.py, it accepts a positional question argument and several traversal modifiers:

graphify query "<question>" \
  [--dfs] \
  [--context <C>] \
  [--budget <N>] \
  [--graph <PATH>]

Key flags:

• --dfs – Switches from breadth-first to depth-first search
• --context <C> – Restricts search to a named context (repeatable)
• --budget <N> – Sets the token budget (default 2000)
• --graph <PATH> – Specifies an explicit graph file path

The affected Sub-Command

Use affected to analyze dependency relationships for a specific node or label. This command, defined around lines 62-94, performs graph traversal to identify impacted components:

graphify affected "<node-or-label>" \
  [--relation <R>] \
  [--depth <N>] \
  [--graph <PATH>]

Parameters:

• --relation <R> – Limits traversal to specific edge types (repeatable)
• --depth <N> – Sets graph traversal depth (default 2)
• --graph <PATH> – Uses a custom graph file instead of the default

Navigation Commands: path and explain

For direct graph navigation, Graphify provides two utilities defined in the early sections of cli.py (lines 11-30 and 13-25):

path – Finds routes between nodes:

graphify path "<source>" "<target>" [--graph <PATH>]

explain – Generates explanations for specific nodes:

graphify explain "<node>" [--graph <PATH>]

Memory and Reflection System

The save-result Sub-Command

The save-result command persists query outcomes to Graphify’s memory system. Located around lines 27-41 in graphify/cli.py, it requires either --answer or --answer-file and supports outcome classification:

graphify save-result \
  --question <Q> \
  (--answer <A> | --answer-file <FILE>) \
  [--type <T>] \
  [--nodes N ...] \
  [--outcome useful|dead_end|corrected] \
  [--correction <TEXT>] \
  [--memory-dir <DIR>]

Critical arguments:

• --question – The original query text (required)
• --answer or --answer-file – The answer content (one required)
• --outcome – Classification tag for the result quality
• --memory-dir – Storage location (defaults to <graphify-out>/memory)

The reflect Sub-Command

The reflect command analyzes stored memories to generate lessons learned. Implemented around lines 55-73, it supports decay algorithms and corroboration thresholds:

graphify reflect \
  [--memory-dir <DIR>] \
  [--out <PATH>] \
  [--graph <PATH>] \
  [--analysis <PATH>] \
  [--labels <PATH>] \
  [--half-life-days <F>] \
  [--min-corroboration <I>] \
  [--if-stale]

Configuration options:

• --half-life-days – Decay rate for lesson weights (default 30)
• --min-corroboration – Minimum useful results required to promote a node (default 2)
• --if-stale – Skips execution if output is newer than inputs
• --out – Output markdown file (default <graphify-out>/reflections/LESSONS.md)

Repository Utility Commands

The prs Sub-Command

The prs command passes arguments directly to the internal PR helper (graphify/prs.py). As noted in cli.py (lines 44-46), this acts as a transparent wrapper:

graphify prs [ARGS...]

The hook Sub-Command

Manage Git hooks integration using the hook sub-command (lines 54-62):

graphify hook <install|uninstall|status>

Operations:

• install – Installs Graphify Git hooks
• uninstall – Removes installed hooks
• status – Displays current hook configuration

Auxiliary Entry Points

Beyond the core CLI in graphify/cli.py, the repository ships additional entry points with independent argument parsers:

• graphify watch – Defined in graphify/watch.py for file system monitoring
• graphify ingest – Implemented in graphify/ingest.py for data ingestion pipelines

Both follow the same argparse pattern as the main CLI, instantiating ArgumentParser and invoking internal functions based on parsed arguments.

Summary

• Graphify CLI centers on graphify/cli.py with nine primary sub-commands: provider, query, affected, path, explain, save-result, reflect, prs, and hook
• Provider management supports custom LLM registration via provider add with --base-url, --default-model, and --env-key requirements
• Graph traversal commands (query, affected) accept --graph overrides and search modifiers like --dfs and --depth
• Memory system uses save-result for storage and reflect for analysis, with configurable decay via --half-life-days and promotion thresholds via --min-corroboration
• Auxiliary scripts (watch, ingest) reside in separate modules but follow identical CLI patterns

Frequently Asked Questions

How do I add a custom OpenAI-compatible provider to Graphify?

Use the provider add sub-command with the required configuration flags. You must specify --base-url for the API endpoint, --default-model for the model identifier, and --env-key for the environment variable containing your API key. Optional pricing flags (--pricing-input and --pricing-output) allow cost tracking per token.

What is the difference between the query and affected commands?

The query command accepts natural language questions and searches the graph for relevant nodes using BFS by default (or DFS with --dfs), while affected performs dependency analysis starting from a specific node or label to identify impacted components. Use query for discovery and affected for impact analysis.

How does the reflection system handle stale data?

The reflect command includes an --if-stale flag that compares timestamps between input memory files and the output markdown. When specified, Graphify skips regeneration if the output file is already newer than the inputs, preventing unnecessary reprocessing of unchanged memory directories.

Where does Graphify store memory files by default?

Memory files default to the <graphify-out>/memory directory, which you can override using the --memory-dir flag in both save-result and reflect commands. Reflection outputs default to <graphify-out>/reflections/LESSONS.md unless changed with the --out parameter.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}