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:
- Rust:
graphforge-api, the public engine facade. - Terminal:
gf, installed fromgraphforge-cli. - Python: the
graphforgewheel. - Node:
@curatelabs/graphforge.
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>):
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.
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.
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.