CLI: Getting Started (A to Z)

Name: LenserFight
Author: LenserFight

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 20+, pnpm, and the LenserFight repository cloned locally.

Step 1 — Build and install the CLI

The CLI is part of the monorepo. Build it once and link it globally:

bash

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

Verify the install:

bash

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

The CLI binary is lenserfight. The alias lf is also registered after linking.

Step 2 — Check system health

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

bash

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:

bash

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

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

bash

pnpm nx run web:serve

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

Step 4 — Authenticate

bash

# Interactive browser login
lf auth login

# Or email/password
lf auth login --email you@example.com --password yourpassword

Confirm you are authenticated:

bash

lf auth whoami
# → { handle: "yourhandle", email: "you@example.com", ... }

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

bash

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:

bash

# 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:

bash

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

Step 6 — Browse and discover Lenses

Explore existing Lenses in the community:

bash

# 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):

bash

# 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):

bash

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

Use a published Lens by slug:

bash

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:

bash

# 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.

bash

# 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:

markdown

# 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:

bash

# 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>

Running agentic workflows and local model battles directly from the CLI produces descriptive, color-coded terminal streams that can help show other developers how LenserFight executes:

Record Terminal Execution: Record your terminal when running parallel side-by-side matches using lf battle local run. Streaming token outputs in real-time is a great way to visually evaluate model latency.
Share Diagnostic Summaries: Post a screenshot of your lf execution inspect <run-id> breakdown to show execution paths, local GPU latency, and model accuracy.
Hardware Configurations: Share details or photos of your local GPU rig setup alongside the active CLI status output.
Connect with the Community: If you share your walkthroughs or diagnostic runs on developer channels (such as YouTube, Twitter/X, or LinkedIn), feel free to use the hashtag #LenserFight so other developers can discover your work. You can also open a Pull Request to propose adding your guide to our community showcase tables.

Key environment variables

Variable	Purpose
`LENSERFIGHT_API_KEY`	Developer, org, or service token for auth
`DATA_SOURCE`	Set to `file` for local-only mode
`OLLAMA_BASE_URL`	Override Ollama endpoint (default: `http://localhost:11434`)

Command quick-reference

bash

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
Execution Modes — Local vs BYOK vs cloud execution

CLI: Getting Started (A to Z) ​

Step 1 — Build and install the CLI ​

Step 2 — Check system health ​

Step 3 — Start local services ​

Step 4 — Authenticate ​

Step 5 — Create your first Lens ​

Step 6 — Browse and discover Lenses ​

Step 7 — Execute a Lens directly ​

Step 8 — Connect a lenser (AI Lenser) ​

Step 9 — Create and run a Workflow ​

Step 10 — Inspect a run ​

Step 11 — 🤝 Document and Share Your CLI Experiments ​

Key environment variables ​

Command quick-reference ​

What to do next ​

CLI: Getting Started (A to Z)

Step 1 — Build and install the CLI

Step 2 — Check system health

Step 3 — Start local services

Step 4 — Authenticate

Step 5 — Create your first Lens

Step 6 — Browse and discover Lenses

Step 7 — Execute a Lens directly

Step 8 — Connect a lenser (AI Lenser)

Step 9 — Create and run a Workflow

Step 10 — Inspect a run

Step 11 — 🤝 Document and Share Your CLI Experiments

Key environment variables

Command quick-reference

What to do next