Operator Cheat Sheet

Tip

Print this page (Cmd+P) for a desk reference.

Install

Download the latest release. The package is self-contained — no Python, Node, or dbt needed.

# macOS
export PATH="$HOME/jinflow:$PATH"
jinflow version

# Verify
jinflow us

First-Time Configuration

jinflow us --live-root ~/jinflow-live            # where tenant data lives
jinflow us millesime.domaine_zufferey                 # set default tenant
jinflow us --api-key sk-ant-...                  # Claude API key (for AI features)
jinflow us --model claude-sonnet-4-6             # AI model selection

Optional: Pack root and DLZ

jinflow us --pack-root ~/jinflow-packs           # domain pack repos
jinflow us --dlz ~/jinflow-datalandingzone       # data landing zone

Optional: R2 cloud credentials

jinflow us --r2-account-id <id>
jinflow us --r2-key <access_key>
jinflow us --r2-secret <secret_key>
jinflow us --r2-bucket jinflow-demo

Credentials stored in ~/.jinflow/secrets.yml.

Config Resolution Order

Setting	1st	2nd	3rd	Default
live_root	JINFLOW_LIVE env	~/.jinflow/config.yml	—	~/.jinflow/live/
pack_root	JINFLOW_PACKS_ROOT env	~/.jinflow/config.yml	engine packs/	—
dlz_root	JINFLOW_DLZ_ROOT env	~/.jinflow/config.yml	AFS jinflow.yml	—
tenant	JINFLOW_TENANT env	~/.jinflow/config.yml	AFS default	—

Tenant Lifecycle

# Create (from scratch)
jinflow init --tenant my_analysis --source-system opale

# Create (from domain pack)
jinflow init --pack millesime --tenant szo --source-system opale

# Clone existing
jinflow clone millesime.domaine_zufferey --name sandbox

# List all
jinflow ls

# List with snapshots
jinflow ls --snapshots

# Interactive picker
jinflow pick

# Health check
jinflow stat

Build Operations

jinflow make                              # build default tenant
jinflow make --all                        # all tenants, all packs
jinflow make millesime                     # all tenants in one pack
jinflow make --clean                      # drop + full rebuild
jinflow make --sync                       # sync DLZ → raw/ first
jinflow make --extract                    # XLSX → CSV → sync → build
jinflow make --snapshot post-audit        # freeze after build
jinflow make --quiet                      # suppress output
jinflow make --continue-on-error          # don't fail-fast

Snapshot Management

jinflow make --snapshot                   # auto-tag: YYYYMMDD-HHMM
jinflow make --snapshot post-audit        # named tag
jinflow snapshot review-q1                # standalone (no build)
jinflow explore --snapshot post-audit     # browse a snapshot
jinflow ls --snapshots szo               # list tenant snapshots

Snapshots are immutable — make refuses to overwrite.

AFS Git Operations

jinflow afs status                        # branch, tags, dirty files
jinflow afs log                           # commit history
jinflow afs diff                          # changes vs remote
jinflow afs pull                          # fast-forward from remote
jinflow afs push -m "Updated probes"      # commit + push
jinflow afs remote https://github.com/... # set remote URL
jinflow afs update --do-it                # sync pack → tenant (three-way merge)
jinflow afs reset --do-it                 # hard reset to pack state

Cloud Sync (R2)

jinflow cloud ls                          # list KLS files + R2 status
jinflow cloud ls --local-only             # skip R2 check
jinflow cloud sync --do-it                # upload to R2
jinflow cloud sync --do-it --prune        # upload + delete stale remote files
jinflow cloud blacklist millesime.domaine_zufferey      # exclude tenant from sync
jinflow cloud blacklist millesime.domaine_zufferey --remove  # re-include

Pack Management

jinflow pack ls                           # list packs and artifacts
jinflow pack ls --sync                    # include tenant sync status
jinflow pack clone millesime               # clone from GitHub (SSH)
jinflow pack clone millesime --https       # clone via HTTPS

Explorer

jinflow explore                           # default tenant, port 4000
jinflow explore --port 3000               # custom port
jinflow explore millesime.domaine_zufferey              # specific tenant
jinflow explore --db /path/to/kls.duckdb  # explicit KLS
jinflow explore --snapshot post-audit     # browse snapshot
jinflow explore --docker                  # run in Docker
jinflow explore --cloud                   # use R2 cloud KLS
jinflow explore --no-open                 # don't open browser

Evolve (AI REPL)

jinflow evolve                            # interactive session
jinflow evolve --no-ai                    # SQL-only mode
jinflow evolve --model claude-opus-4-6    # choose model

Instance Management

jinflow instance ls                                    # list registered instances
jinflow instance add demo https://this-is.jinflow.io   # register an instance
jinflow instance remove demo                           # remove an instance
jinflow instance refresh demo                          # tell instance to re-download from R2
jinflow instance refresh --all                         # refresh all instances

Notebook Export

jinflow notebook-pdf nb_io_reconciliation                  # export as PDF
jinflow notebook-pdf nb_io_reconciliation --lang de        # German
jinflow notebook-pdf nb_io_reconciliation -o report.pdf    # custom output

Drift Detection

python3 scripts/docsdrift.py              # full report
python3 scripts/docsdrift.py --quiet      # exit 1 if drift (CI-ready)

Releasing

just release patch                        # bump + tag + build
just release minor
just release major
just release 1.1.0                        # explicit version

Pipeline: bump version → generate release notes → commit + tag → CI builds → local macOS build.

Deploy Package Layout

jinflow-deploy/
  _cli/jinflow/              PyInstaller binary (CLI + dbt + DuckDB)
  _explorer/                 SvelteKit build + duckdb-async
  jinflow                    macOS/Linux launcher
  jinflow.bat                Windows launcher

~200 MB, self-contained. No Python/Node/dbt required on target machine.

Tenant Directory Layout

{live_root}/{pack}/{tenant}/
  afs/        ← analytical framework (git-backed)
  raw/        ← immutable source CSVs
  build/      ← intermediaries
  store/      ← KLS + SIS + snapshots
    {pack}_{tenant}_kls.duckdb       working KLS
    {pack}_{tenant}_sis.duckdb       mutable SIS
    YYYYMMDD-HHMM_kls.duckdb        auto snapshot
    post-audit_kls.duckdb            named snapshot

Key Files

File	Location	Purpose
~/.jinflow/config.yml	User config	live_root, pack_root, dlz_root, tenant
~/.jinflow/secrets.yml	Credentials	API keys, R2 credentials
.githooks/commit-msg	Repo	Semantic commit prefix enforcement
state/system.duckdb	Repo	Optional system DB (instrument lifecycle)
.jinflow.yml	AFS root	Pack manifest, tenant config

Troubleshooting

Symptom	Cause	Fix
dbt fails with wrong adapter	System dbt is dbt-fusion	Use .venv/bin/dbt
KLS catalog error with dots	Dots in DuckDB filename	Use underscores: pack_tenant_kls.duckdb
Hook rejects commit	Missing semantic prefix	Start message with feat:, fix:, etc.
jinflow make skips phases	Incremental build	Use --clean for full rebuild
Explorer shows stale data	KLS not rebuilt	Run jinflow make, refresh browser
afs update shows conflicts	Pack and tenant both changed same file	Use --force (pack wins) or merge manually