# graphforge-cli
GraphForge command-line interface.
This crate is an internal layer of [GraphForge](https://graphforge.sh), a Rust
graph engine with Arrow results and Parquet storage. Most applications should
start with one of these entry points:
- Rust: [`graphforge-api`](https://crates.io/crates/graphforge-api), the public engine facade.
- Terminal: `gf`, installed from [`graphforge-cli`](https://crates.io/crates/graphforge-cli).
- Python: the [`graphforge` wheel](https://pypi.org/project/graphforge/).
- Node: [`@curatelabs/graphforge`](https://www.npmjs.com/package/@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](https://github.com/apache/datafusion/issues/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](https://github.com/CurateLabs/graphforge/issues/2084)).
The planning fix ships in DataFusion 55. The spill fix
([apache/datafusion#24891](https://github.com/apache/datafusion/pull/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>`):
```sh
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](https://docs.graphforge.sh/guide/quickstart/) 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:
```sh
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](https://docs.graphforge.sh/guide/work-with-an-agent/)).
```sh
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](https://docs.graphforge.sh/guide/portable-projects/).
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](https://github.com/CurateLabs/graphforge/blob/main/docs/adr/0053-hub-publish-wire-contract.md#explicit-history-mutation-intent).
[Documentation](https://docs.graphforge.sh/) ·
[Repository](https://github.com/CurateLabs/graphforge) ·
[Architecture](https://github.com/CurateLabs/graphforge/blob/main/docs/book/architecture/ast-and-planning.md)