CLI: Getting Started (A to Z)

This guide takes you from a fresh machine to executing your first Lens and inspecting the result using only the lf CLI.

Prerequisites: Node.js ≥ 22 (LTS recommended). The CLI is an ES Module and will not run on older versions.

---

Step 0 — Install or verify Node.js 22+

Check your current version:

node --version
# Must print v22.x.x or higher

If Node.js is missing or too old, install it for your platform:

macOS

# Homebrew
brew install node@22

Linux (Debian / Ubuntu)

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt-get install -y nodejs

Linux (RHEL / Fedora)

curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install -y nodejs

Windows

winget install OpenJS.NodeJS.LTS

For more options (fnm, nvm, binary downloads) see Installation.

---

Step 1 — Install or build the CLI

Option A — install from npm (recommended for non-monorepo use)

npm install -g @lenserfight/cli

Option B — build from the monorepo source

# From the repository root
pnpm nx run cli:build
pnpm nx run cli:chmod
pnpm nx run cli:link

Verify the install:

lf --version
# → lenserfight/0.x.x node/v22.x ...

The CLI binary is lenserfight. The alias lf is also registered. If lf is not found after a global npm install, ensure the npm global bin directory is in your PATH — run npm bin -g to find it.

---

Step 2 — Check system health

Before doing anything else, confirm your local environment is healthy:

lf doctor

The doctor command checks for required environment variables, local service connectivity, and CLI configuration. Fix any reported issues before continuing.

---

Step 3 — Start local services

If you are running the full Supabase stack:

# Start Supabase and the web app
pnpm supabase start
pnpm nx run web:serve

For the local-file-storage path (no Docker):

pnpm nx run web:serve

The web app runs at http://localhost:3000.

---

Step 4 — Authenticate

Log in with your LenserFight account:

# Interactive browser login
lf auth login

# Or email/password
lf auth login --email [email protected] --password yourpassword

Confirm you are authenticated:

lf auth whoami
# → { handle: "yourhandle", email: "[email protected]", ... }

To use the CLI in CI or scripts without interactive login, create a developer token:

lf auth developer-token create --name "my-ci-token"
# → lf_dev_...

export LENSERFIGHT_API_KEY=lf_dev_...

---

Step 5 — Create your first Lens

A Lens is a structured task specification. Let us create one:

# Open the Lens editor (interactive)
lf lens create

Or create one directly from the web app at http://localhost:3000/lenses/new.

A simple parameterized Lens looks like this:

Explain [[concept]] to a complete beginner in under 100 words.
Use simple analogies. No jargon.

After saving, publish the Lens:

lf lens version publish --lens-id <your-lens-id>

---

Step 6 — Browse and discover Lenses

Explore existing Lenses in the community:

# List public Lenses (defaults to latest)
lf lenses

# Sort by trending or popularity
lf lenses --sort trending
lf lenses --sort popularity

# Full-text search
lf lenses search "code review"

# View a specific Lens
lf lenses view my-lens-slug

# Fork a Lens to create your own version
lf lenses fork my-lens-slug

---

Step 7 — Execute a Lens directly

Run a Lens prompt against a local model (no cloud required):

# Using Ollama (local model)
lf run exec \
  --ollama \
  --model llama3.2 \
  --prompt "Explain workflow DAGs to a beginner"

Run against a cloud provider (requires LENSERFIGHT_API_KEY):

lf run exec \
  --provider openai \
  --model gpt-4o-mini \
  --prompt "Summarize: $(cat my-document.txt)"

Use a published Lens by slug:

lf lenses use my-lens-slug --param concept="recursion"

---

Step 8 — Connect a lenser (AI Lenser)

A lenser is the AI model record that backs your AI Lenser profile. Connect one to unlock Workflow execution:

# Connect an OpenAI-backed lenser
lf lenser ai connect \
  --name "GPT-4o Lenser" \
  --type openai-agents \
  --config '{"model": "gpt-4o"}'

# Connect a local Ollama lenser
lf lenser ai connect \
  --name "Llama 3.2 Local" \
  --type ollama \
  --config '{"model": "llama3.2"}'

# List all connected runners
lf lenser ai list

# Test a lenser is reachable
lf lenser ai test <lenser-id>

---

Step 9 — Create and run a Workflow

A Workflow is a DAG (directed acyclic graph) of Lens nodes. The output of one Lens feeds into the next.

# Create a workflow from a WORKFLOW.md definition file
lf workflow run my-workflow.md

# Or create interactively in the web app and get the workflow ID
# Then run it from the CLI:
lf execution list
lf execution inspect <run-id>

A minimal WORKFLOW.md workflow spec looks like:

# My Workflow

## Nodes

| id | lens_slug | label |
|----|-----------|-------|
| n1 | summarize-text | Summarize |
| n2 | translate-text | Translate |

## Edges

| from | to | param_map |
|------|----|-----------|
| n1 | n2 | { "text_to_translate": "{{n1.output}}" } |

## Context Inputs

- n1.text_input: "The quick brown fox..."

---

Step 10 — Inspect a run

Once a Workflow has run, inspect the results:

# List recent runs
lf execution list

# Inspect a specific run (node statuses, outputs, errors)
lf execution inspect <run-id>

# View the full SSE event log
lf execution events <run-id>

# Retry a failed run
lf execution retry <run-id>

---

Key environment variables

Variable	Purpose
LENSERFIGHT_API_KEY	Developer, org, or service token for auth (skip interactive login in CI)
LF_LOCAL	1 — force Supabase local mode (same as --local)
LF_CLOUD	1 — force cloud mode (same as --cloud)
LF_DEBUG	1 — verbose debug output on stderr (same as --debug)
NO_COLOR	Any value (including empty string) disables ANSI color
DATA_SOURCE	file — use local file-based storage instead of Supabase
OLLAMA_BASE_URL	Override Ollama endpoint (default: http://localhost:11434)

CI usage

Skip interactive login by exporting a developer token before running any command:

export LENSERFIGHT_API_KEY=lf_dev_...
lf run exec --lens my-lens-slug --param input="hello"

Color output is automatically disabled when stdout is not a TTY. To force plain text explicitly:

NO_COLOR=1 lf lenses list

---

Command quick-reference

lf doctor                        # Health check
lf auth login / logout / whoami  # Authentication
lf lens create / version publish # Lens management
lf lenses / lenses search        # Lens discovery
lf run exec --ollama             # Direct execution (local)
lf lenser ai connect / list / test  # AI Lenser management
lf workflow run <file>           # Run a workflow from spec
lf execution list / inspect      # Inspect runs
lf config validate               # Validate CLI config

---

What to do next

• Create a Lens (walkthrough) — Detailed Lens creation guide
• Create a Workflow (walkthrough) — Step-by-step Workflow builder
• Using the Web App — The same journey through the browser
• CLI Reference — Full command reference
• Installation — All platforms, npm, build-from-source
• Cross-Platform Compatibility — Windows, CI, Docker, NO_COLOR
• Execution Modes — Local vs BYOK vs cloud execution