Quickstart: the CLI

Create a repository, commit a file, and read the result with stock fossil. The libfossil command drives the same code as the library, and the file it writes is an ordinary Fossil repository.

Create a repository and a checkout

libfossil repo new notes.fossil
mkdir work && cd work
libfossil -R ../notes.fossil repo open .

created repository: notes.fossil
opened checkout in . (repo: /home/ana/notes.fossil)
empty repository -- no checkins yet

repo open writes a .fslckout file in the directory. Commands run inside the checkout find the repository through it, so -R is only needed to open it.

Commit

echo '# notes' > README.md
libfossil repo add README.md
libfossil repo ci -m "first notes" --user ana

ADDED    README.md
checkin 542a963405 (rid=2)

The check-in name is the hash of the manifest, which includes the time, so yours differs. --user sets the name on the check-in; without it the OS user name is used.

Read the history

libfossil repo timeline

542a963405  2026-10-23 21:00  ana  first notes

The repository is a Fossil repository, so the fossil binary reads it unchanged:

fossil timeline -R ../notes.fossil

=== 2026-10-23 ===
21:00:14 [542a963405] first notes (user: ana tags: trunk)
+++ no more data (1) +++

Next

• Embed in Go: the same steps from a Go program.
• First sync: serve the repository and clone it.
• CLI reference: every command and flag.
• Migrating from fossil: how the commands map to fossil’s.