graphforge-cli 0.6.0-rc.7

GraphForge command-line interface
Documentation

graphforge-cli

GraphForge command-line interface.

This crate is an internal layer of GraphForge, a Rust graph engine with Arrow results and Parquet storage. Most applications should start with one of these entry points:

Use matching versions across the engine and bindings. Before v1.0.0, GraphForge does not guarantee backward compatibility or project migration.

Known issue. Crates installed from crates.io build against stock DataFusion 54.1. GraphForge's own builds carry two DataFusion fixes that crates.io builds lack. Those builds are the Python wheel and the Node packages, including their gf CLI. The two fixes are:

  • a hang when a query spills under memory pressure (apache/datafusion#24883);
  • a planning error when a join's keys read fields of one struct, such as two node patterns keyed off one unwound map (#2084).

The planning fix ships in DataFusion 55. The spill fix (apache/datafusion#24891) is on DataFusion's main branch but not yet in a release. Crates.io builds get each fix when GraphForge moves to a DataFusion release that contains it.

Quickstart

Install the version shown on this crate page (replace <version>):

cargo install graphforge-cli --version <version> --locked
gf --version
gf --help
mkdir my-graph
cd my-graph
gf init
gf skills status

gf init creates repository-local GraphForge configuration and installs the embedded agent skills. Durable projects require writable local storage: ext4, XFS or Btrfs on Linux, non-removable local APFS on macOS, or fixed local NTFS on Windows. Native filesystem admission checks still apply. Follow the first graph guide to load and query connected data.

Research workflow

Research history has a git-style command set. A Branch is named by its label, and the label is the ref on the Hub. From an existing durable Project containing the sample Item nodes (adapt the query to your graph), work locally:

gf config user --name "Ada Lovelace" --email ada@example.org   # credit on Versions
gf branch main                       # first Branch of the Project
gf commit -m "Raise scores" --query "MATCH (n:Item) SET n.score = 2"
gf tag v1                            # name the head; list with gf tag, delete with -d
gf status                            # Branch, head, upstream, commits not yet published
gf log                               # history; --all, -n <count>, <tag>, --remote
gf branch feature/score              # another Branch; gf switch feature/score selects it

gf commit runs the query against the Branch and records the message as the Version description. Author and committer come from --author/--committer, then GF_AUTHOR/GF_COMMITTER, then gf config user. --ref always names a Branch by its label. gf pull records a two-parent Version; it never moves a head without one. The gf research commands are the underlying native JSON verbs; each help text points at its plain-argument form.

Publish research history

Authors and committers recorded on Versions are always published, in the lineage and as the Project summary's derived people list; published credit is public and permanent, and there is no redaction option.

Use a separately verified server implementing graphforge-discovery/1 and graphforge-hub-publish/1, an existing owner account and repository, and a publish:owner/repository-scoped credential. The CLI walkthrough tests use the native reference Hub at https://hub.test, not a public write service. These tests and examples do not qualify production publishing. Replace the placeholder https://hub.example below with your verified server; supply the credential securely through GRAPHFORGE_HUB_PUBLISH_TOKEN (see the agent guide).

gf push https://hub.example/owner/repository --ref main --token-env GRAPHFORGE_HUB_PUBLISH_TOKEN
gf clone https://hub.example/owner/repository collaborator --ref main

Work from the cloned Project's directory before committing. Later gf push uses its tracked repository/ref; gf pull incorporates a collaborator's new head of that same ref. Clone with --tag v1 instead of --ref main for the tagged Version. Tags travel in the published lineage, not as separate Hub refs. Clone/pull here assume public read access; a publish token is not a read token. For exchange without a write server, use the portable export/import guide.

History replacement is explicit: gf publish <repository> --ref main --rewrite requests a non-fast-forward replacement under the current revision lease. --prune separately removes unreachable published history where the Hub offers history-mutation@1; neither flag merges divergent contents. Other refs and native history dependencies remain protected. Established Fork updates retain independent bytes; optional --check-fork-origin <repository URL> checks the immutable citation without guessing its Hub host. See the publish contract.

Documentation · Repository · Architecture