CLI

The loonfs CLI manages LoonFS profiles, namespaces, filesystem content, revision history, and maintenance. It can connect directly to object storage in embedded mode or to a LoonFS server in remote mode.

Install

Install the latest release on macOS or Linux with the install script:

curl -fsSL https://install.loonfs.com | sh
loonfs version

With Homebrew:

brew install loonfs/tap/loonfs

Or build the CLI from source:

cargo build --release -p loonfs-cli
cp ./target/release/loonfs ~/.local/bin/loonfs

Quickstart

This local embedded profile is useful for trying LoonFS without a server or cloud credentials. local-fs is intended for development and testing; use a cloud object store or remote profile for a durable deployment.

loonfs init default --no-input \
  --mode embedded \
  --store-kind local-fs \
  --root "$HOME/.loonfs/data"

loonfs namespace create demo
loonfs use demo

printf 'Hello from LoonFS\n' | loonfs put - /hello.txt
loonfs ls /
loonfs cat /hello.txt

Run loonfs init without flags for an interactive setup. loonfs current shows the active profile and its default namespace.

Profiles and deployment modes

A profile tells the CLI where LoonFS runs. Commands use the default profile and namespace unless you pass --profile or --namespace.

• Embedded profiles access object storage directly from the CLI process. Supported stores are local filesystem, Amazon S3, Cloudflare R2, Google Cloud Storage, and Azure Blob Storage.
• Remote profiles connect to a running LoonFS server. Use this mode when many clients need to write concurrently or when object-store credentials should remain on the server.

For example, create an embedded S3 profile using the standard AWS credential environment variables:

export AWS_ACCESS_KEY_ID={access_key_id}
export AWS_SECRET_ACCESS_KEY={secret_access_key}

loonfs --no-input profile create production \
  --mode embedded \
  --store-kind aws-s3 \
  --bucket {bucket_name} \
  --region {aws_region}

loonfs profile use production

Or connect to a LoonFS server:

export LOONFS_AUTH_TOKEN={auth_token}

loonfs --no-input profile create production \
  --mode remote \
  --server-url https://loonfs.example.com

loonfs profile use production

Embedded mode is production-capable when backed by a compatible object store, but only one writer session can own a namespace at a time. Concurrent embedded writers can fence one another; a fenced command commits nothing and is safe to rerun. A LoonFS server coordinates concurrent remote clients.

Everyday commands

Task	Commands
Profiles	profile create, profile list, profile show, profile update, profile delete, profile use
Namespaces	namespace create, namespace fork, namespace delete, use, current
Read	ls, stat, cat, get, grep
Write	put, mkdir, mv, cp, rm
History and recovery	revisions, restore, trash, undelete, changes
Maintenance	admin run, admin step, admin gc, admin checkpoint, admin index-enable

Common filesystem operations look like this:

loonfs put ./report.md /reports/report.md
loonfs mkdir -p /archive/2026
loonfs cp /reports/report.md /archive/2026/report.md
loonfs mv /reports/report.md /reports/final.md

loonfs stat /reports/final.md
loonfs get /reports/final.md ./final.md
loonfs rm /reports/final.md

Use -r with put, get, cp, or rm to operate on a directory tree. Moving a directory is already atomic and does not require -r.

Content search

loonfs grep searches file contents and can restrict results to a subtree:

loonfs grep 'TODO|FIXME' --path-prefix /projects -i

Patterns support regular expressions without backreferences or lookaround assertions. Indexed searches need a run of at least three consecutive literal bytes, typically three ASCII characters. Use --allow-scan to permit a capped exhaustive scan when a pattern cannot use the index, or --allow-stale to accept indexed-only results when the unindexed tail exceeds the scan budget.

Safe writes and recovery

Filesystem commands that commit (put, mkdir, rm, mv, cp, restore, and undelete) accept -m or --message to annotate the commit. They also accept --commit-id as an idempotency key: rerun the same request with the same ID to retry safely. When omitted, LoonFS generates an ID and includes it in the result.

loonfs put ./proposal.md /proposals/acme.md \
  --message "Add initial proposal" \
  --commit-id proposal-acme-v1

Use --expected-revision with put --force for a conditional replacement that fails if another writer changed the file first.

Deletes are recoverable. loonfs rm returns the deletion handle, and loonfs trash lists it again. Pass that handle to loonfs undelete; omit the destination path to restore the original binding.

loonfs trash
loonfs undelete --inode {inode_id} --deleted-at {change_seq}

loonfs revisions lists a file’s retained revisions, while loonfs restore writes an older revision as the new current revision.

Transfers

loonfs put and loonfs get stream large files with bounded memory and show transfer progress on stderr. Recursive transfers use bounded concurrency and commit file by file.

Interrupted transfers are resumable where the transport supports it. Rerun the same command: downloads reuse a verified partial file, and remote multipart uploads reuse completed parts. --no-progress disables progress output.

Automation and agents

The CLI works directly from any agent or automation environment that can run shell commands. Use the global flags to make execution deterministic and machine-readable:

loonfs --json --no-input --no-progress stat /reports/final.md

• --json emits a stable JSON success or error envelope.
• --no-input fails instead of prompting.
• --no-progress suppresses transfer progress events on stderr.
• --config selects a config file explicitly; LOONFS_CONFIG is the environment-variable equivalent.
• --no-retry disables bounded retries for transient server and transport failures.

loonfs cat and loonfs get ... - stream raw file bytes to stdout and therefore reject --json.

Maintenance

Remote servers run maintenance for the namespaces they host. Embedded deployments must assign it explicitly:

# Host maintenance until interrupted.
loonfs admin run --namespace demo

# Catch the namespace up and exit, suitable for a scheduled job.
loonfs admin run --namespace demo --drain

Other admin commands manage WAL flushing, retention, garbage collection, checkpoints, object-store contract probes, and the content index. Run loonfs admin --help before using them in production.

Command reference

Run loonfs --help or loonfs <command> --help for the installed version’s exact flags. The repository also contains the complete CLI reference.