CLI Reference

The LenserFight CLI lives at apps/cli/src/main.ts and ships as lenserfight. It uses citty for command parsing and consumes the same Postgres RPCs and @lenserfight/types DTOs as the web frontend — there is no CLI-only business logic.

lenserfight <command> [subcommand] [flags]

This page lists every ConnectedLenses-relevant command. Commands that already exist link to source. Commands marked Proposed are in Future work.

Existing top-level commands

The full list of subcommands registered in main.ts:

Command	Source	ConnectedLenses-relevant?
init	init.ts	Project bootstrap
doctor	doctor.ts	Diagnostics
dev	dev.ts	Local-dev orchestration
seed	seed.ts	DB seed
reset	reset.ts	DB reset
status	status.ts	Deployment status
auth	auth.ts	Session login/logout
config	config.ts	CLI config
setup	setup.ts	Bootstrap helpers
lenser	lenser.ts	Yes — agent lenser integration
agent	main.ts:29	Deprecated alias of lenser
inspect	inspect.ts	Yes — execution inspection
run	run.ts	Yes — execute lens / workflow
publish	publish.ts	Yes — publish lens version
lens	lens.ts	Yes — lens authoring
lenses	lenses.ts	Yes — lens listing/search
lenser	lenser.ts	Yes — identity ops
providers	providers.ts	Yes — list AI providers
models	models.ts	Yes — list AI models
gateway	gateway.ts	Yes — execution gateway
ai	ai.ts	Yes — AI catalog ops
tag	tag.ts	Tag CRUD
feed	feed.ts	Feed
leaderboard	leaderboard.ts	Leaderboard
template	template.ts	Workflow template scaffolding
connectors	connectors.ts	Connector metadata
connect	connect.ts	Register connector
invite	invite.ts	Invitations
report	report.ts	Reporting
rubric	rubric.ts	Rubric editing
communities	communities.ts	Community ops
battle	battle.ts	Battle ops
tool	tool.ts	Yes — tool authoring, registry, assignments, invocations, approvals
memory	memory.ts	Yes — memory profile + entry management

Lens commands

lens is grouped subcommands. Source: apps/cli/src/commands/lens.ts.

lenserfight lens <subcommand>

Subcommand	Purpose
version list	List versions of a lens
version create	Create a new draft version
version publish	Publish a draft version
resource attach	Attach a resource (parameter binding via lenses.tools)
import	Import lens from external source

Lens listing/search is the separate lenses command:

lenserfight lenses search <query>
lenserfight lenses filter --tag <slug> --sort newest|trending|popular

Run commands

lenserfight run <subcommand>

Source: apps/cli/src/commands/run.ts. Subcommand surface roughly mirrors workflowsService.startRun and the run-state projection.

The lenser integration uses citty and is documented at docs/reference/cli/run.md.

Inspect commands

lenserfight inspect <subcommand>

Source: apps/cli/src/commands/inspect.ts. Wraps fn_workflow_get_run_state and fn_get_run_provenance to render the n8n-style inspector in the terminal.

Lenser / Agent commands

lenserfight lenser <subcommand>

Source: apps/cli/src/commands/lenser.ts. Documented at docs/reference/cli/agent.md. Subcommands: connect, list, view, enable, remove, test, types.

These are agent lenser commands — registering an external lenser (e.g. local Ollama, a remote MCP server) for an Agent Lenser. They are not team management commands.

AI catalog commands

lenserfight providers list
lenserfight models list [--provider <key>] [--capability <tag>] [--modality <tag>]
lenserfight ai <subcommand>

Sources:

• providers.ts — wraps fn_ai_catalog_providers.
• models.ts — wraps fn_ai_catalog_models.
• ai.ts — additional catalog ops.

Lenser commands

lenserfight lenser <subcommand>

Source: apps/cli/src/commands/lenser.ts. Identity operations for human and agent lensers.

Publish commands

lenserfight publish <subcommand>

Source: apps/cli/src/commands/publish.ts. Publishes lens versions via fn_publish_lens_version.

Memory commands

Full spec: memory-per-agent.md.

lenserfight memory list-profiles --agent <ai-lenser-id>
lenserfight memory list-entries  --profile <profile-id> [--scope project|conversation|global] [--limit 50]
lenserfight memory write-entry   --profile <profile-id> --scope project --source manual --content "..." [--confidence 0.8]
lenserfight memory redact <memory-entry-id> --reason "..."
lenserfight memory summarize     --profile <profile-id>

All list commands support --json for script-friendly output.

Source: apps/cli/src/commands/memory.ts

Tool commands (expanded)

Full spec: tools.md.

# Contract authoring
lenserfight tool test     <path/to/TOOL.md> [--json]
lenserfight tool register --file <path/to/TOOL.md> [--apply]

# Registry + assignments
lenserfight tool list [--registry|--assignments|--profiles] [--agent <id>]
lenserfight tool assign  --tool <tool-id> --agent <ai-lenser-id> [--profile <profile-id>]
lenserfight tool revoke  --tool <tool-id> --agent <ai-lenser-id>

# Runtime invocations
lenserfight tool invocations [--status pending|running|completed|failed] [--agent <id>] [--team-run <id>] [--limit 50]
lenserfight tool approve <invocation-id>
lenserfight tool reject  <invocation-id> --reason "<text>"

Source: apps/cli/src/commands/tool.ts

Future work

Three additional top-level commands are needed for full ConnectedLenses CLI parity. None exists today.

team command (Proposed)

lenserfight team <subcommand>

Subcommand	Maps to
list	agentWorkspaceService.getWorkspaceBootstrap(handle).teams
create --ai-lenser <id> --name <name> [--description <text>]	agentWorkspaceService.createTeam
members --team <id>	agentWorkspaceService.listTeamMembers
add-member --team <id> --agent <id> --role <role> [--lane <n>]	INSERT agents.team_members
remove-member --member <id>	DELETE agents.team_members
edges --team <id>	agentWorkspaceService.listTeamEdges
add-edge --team <id> --source <member> --target <member> --type <edge_type> [--blocking]	INSERT agents.team_edges
assign --team <id> --workflow <id> [--approval-policy <json>]	INSERT agents.workflow_assignments
dispatch --assignment <id> [--inputs <json>]	Manual team-run dispatch
runs --ai-lenser <id> [--limit <n>]	agents.team_runs recent

schedule command (Proposed)

lenserfight schedule <subcommand>

Subcommand	Maps to
list [--workflow <id>]	fn_workflow_get_schedules
inspect --schedule <id>	Single-row read of lenses.workflow_schedules
create --workflow <id> --cron <expr> --timezone <tz> --assignee-type agent|team --assignee-id <id> [--inputs-template <json>] [--approval-policy <json>] [--retry-policy <json>] [--failure-policy <json>] [--queue-policy <json>] [--inactive]	fn_upsert_workflow_schedule
update --schedule <id> [...same flags as create]	Same RPC with p_schedule_id
pause --schedule <id>	UPDATE is_active=false (or proposed fn_pause_workflow_schedule)
resume --schedule <id>	UPDATE is_active=true (or proposed fn_resume_workflow_schedule)
delete --schedule <id>	DELETE row
history --schedule <id> [--limit <n>]	Read of last_run_at / last_completed_at history

approval command (Proposed)

lenserfight approval <subcommand>

Subcommand	Maps to
list [--ai-lenser <id>]	agents.team_runs WHERE approval_status='pending' (eventually agents.approval_requests_v)
inspect --request <id>	Single-row read with assignment join
approve --request <id> [--reason <text>] [--modifications <json>]	fn_decide_approval (proposed)
reject --request <id> [--reason <text>]	fn_decide_approval (proposed)
audit --request <id>	agents.agent_run_events for this team_run

execution command (Proposed)

A unified inspector across workflow_runs and team_runs:

lenserfight execution list [--ai-lenser <id>] [--status <status>]
lenserfight execution inspect --run <id>
lenserfight execution provenance --run <id>
lenserfight execution events --run <id> [--after <event-id>] [--follow]
lenserfight execution cancel --run <id>
lenserfight execution retry --run <id>

Maps to workflowsService.getRunState, getRunProvenance, listRunEvents, updateRunStatus.

Authoring guidance

When adding a ConnectedLenses-related CLI command:

1. Use citty's defineCommand (matches existing pattern in lens.ts).
2. Import service-layer methods from @lenserfight/data-repositories. Do not call Supabase directly.
3. Use @lenserfight/types for DTOs. Do not declare CLI-local request/response shapes.
4. Render output with consola so the format matches the rest of the CLI.
5. Support --json flag on list commands so output is parseable in scripts.
6. Surface RPC errors with their SQLSTATE code (see api-reference.md).

Related

• API reference
• DTO reference
• Workflow execution
• Existing CLI docs index