Skip to content

README.md

Latest commit

 

History

History
157 lines (116 loc) · 6.33 KB

README.md

File metadata and controls

157 lines (116 loc) · 6.33 KB
Raw

Fluree CLI

The fluree command-line interface provides a convenient way to manage ledgers, run queries, and perform transactions without running a server.

Installation

Build from source:

cargo build --release -p fluree-db-cli

The binary will be at target/release/fluree.

Quick Start

# Initialize a project directory
fluree init

# Create a ledger
fluree create myledger

# Insert data
fluree insert '@prefix ex: <http://example.org/> .
ex:alice a ex:Person ; ex:name "Alice" .'

# Query
fluree query 'SELECT ?name WHERE { ?s <http://example.org/name> ?name }'

Global Options

Option Description
-v, --verbose Enable verbose output
-q, --quiet Suppress non-essential output
--no-color Disable colored output (also respects NO_COLOR env var)
--config <PATH> Path to config file
--memory-budget-mb <MB> Memory budget in MB for bulk import (0 = auto: 60% of system RAM). Affects chunk size, concurrency, and run budget when creating a ledger with --from. Set this to cap memory use; auto-detected thread count shrinks to fit it.
--parallelism <N> Number of parallel parse threads for bulk import (0 = auto: most logical cores, capped to fit the memory budget; explicit values honored as-is, floored at 1). Used when creating a ledger with --from.
-h, --help Print help
-V, --version Print version

Commands

Core Commands

Command Description
init Initialize a new Fluree project directory
create Create a new ledger
use Set the active ledger
list List all ledgers
info Show detailed information about a ledger
drop Drop (delete) a ledger
graph Manage named graphs within a ledger (list, drop)
insert Insert data into a ledger
upsert Upsert data (insert or update existing)
update Update with WHERE/DELETE/INSERT patterns
query Query a ledger
validate Validate data against SHACL shapes (report)
history Show change history for an entity
export Export ledger data
log Show commit log
show Show decoded commit contents (flakes with resolved IRIs)
index Build or update the binary index (incremental)
reindex Full reindex from commit history

Remote Sync

Command Description
remote Manage remote servers
upstream Manage upstream tracking configuration
fetch Fetch refs from a remote
clone Clone a ledger from a remote (full commit download)
pull Pull commits from upstream
push Push to upstream remote
track Track remote-only ledgers (no local data)

Clone and pull transfer commits and, by default, binary index data from the remote (pack protocol), so the local ledger is query-ready without a separate reindex. Use --no-indexes to skip index transfer and reduce download size; run fluree reindex afterward if you need the index. Large transfers may prompt for confirmation before streaming.

Server Management

Command Description
server Manage the Fluree HTTP server (run, start, stop, status, restart, logs)

Start a server directly from a project directory — it inherits the same .fluree/ context (config, storage) as the CLI. See server for details.

Implementers

If you're building a custom server that must support the CLI end-to-end (for example, integrating into another app), see:

Authentication

Command Description
token Create, inspect, and manage JWS tokens
auth Manage bearer tokens stored on remotes (login/logout/status)

Configuration

Command Description
config Manage configuration
prefix Manage IRI prefix mappings
completions Generate shell completions

Developer Memory

Command Description
memory Store and recall facts, decisions, constraints, preferences, and artifact references
mcp Unified MCP server for IDE agents — selectable memory / docs toolsets
docs Search the embedded, version-pinned documentation (also the MCP docs toolset)

For background, IDE setup, team workflows, and the mem: schema, see the Memory section of the docs.

Project Structure

When you run fluree init, a .fluree/ directory is created with:

.fluree/
├── active          # Currently active ledger name
├── config.toml     # Configuration settings
├── prefixes.json   # IRI prefix mappings
└── storage/        # Ledger data storage

Input Resolution

Commands that accept data input (insert, upsert, update, query) use flexible argument resolution:

Arguments Behavior
(none) Active ledger; provide input via -e, -f, or stdin
<arg> Auto-detected: if it looks like a query/data, uses it inline; if it's an existing file, reads from it; otherwise treats it as a ledger name
<ledger> <input> Specified ledger + inline input

Input is resolved in this priority order: -e flag > positional inline > -f flag > positional file > stdin.

Data Format Detection

The CLI auto-detects data format based on content:

  • Lines starting with @prefix or @base → Turtle
  • Content starting with { or [ → JSON-LD
  • Leading MATCH/MERGE/CREATE (/DETACH, or a .cypher/.cyp/.cql file → Cypher
  • SPARQL query/update keywords (SELECT/INSERT/DELETE/PREFIX) → SPARQL
  • Files with .ttl extension → Turtle
  • Files with .json or .jsonld extension → JSON-LD

You can override with --format turtle, --format jsonld, --format sparql, or --format cypher (see the per-command docs for the exact set each accepts).