Skip to content

reference.md

Latest commit

 

History

History
139 lines (113 loc) · 4.83 KB

reference.md

File metadata and controls

139 lines (113 loc) · 4.83 KB

Command reference

This page groups the main fclt commands by job. Use fclt --help and fclt <command> --help for exact flags.

Discovery

fclt status [--json]
fclt doctor [--json] [--repair]
fclt paths [--json]
fclt scan [--from <path>] [--json] [--show-duplicates]
fclt inventory [--json] [--tool <name>] [--show-secrets]
fclt list [skills|mcp|agents|snippets|instructions|automations]
fclt show <selector>
fclt find <query>

Use these first. They let you inspect tool state without claiming ownership of any files. doctor --json is read-only and reports setup health, issues, and recommended actions. paths --json reports canonical, generated, runtime, and review paths for agents and integrations.

Use fclt doctor --repair as the one-command self-heal path for local state. It repairs legacy generated state, stale Codex authoring paths, explicit project sync policy, invalid canonical global guidance, and missing Markdown review artifacts. Destructive-looking canonical repairs keep a backup under .ai/.facult/backups/doctor/.

doctor renders AGENTS.global.md in memory before judging it. That file is a source template, so empty fclty blocks and ${refs.work_units} placeholders are valid when they render into filled, concrete tool guidance. doctor flags the global docs only when the rendered output still has empty managed sections, unresolved placeholders, or marker errors. It also checks direct-readable instruction files for leaked ${refs.*} placeholders and can repair known refs there with backups.

Graph

fclt graph show <selector>
fclt graph deps <selector>
fclt graph dependents <selector>

The graph explains how instructions, snippets, config refs, and rendered targets relate.

Canonical Store

fclt templates list
fclt templates init operating-model [--global|--project|--root PATH] [--update] [--force]
fclt templates init project-ai [--update] [--force]
fclt templates init instruction <name>
fclt templates init snippet <marker>
fclt templates init skill <name>
fclt templates init agent <name>
fclt templates init mcp <name>
fclt templates init automation <template-id> --scope global|project|wide
fclt consolidate --auto keep-current --from <path>
fclt index [--force]

Use these to create or normalize canonical capability in ~/.ai or <repo>/.ai.

Managed mode

fclt setup codex-plugin [--dry-run] [--json] [--no-codex-install]
fclt manage <tool> [--dry-run] [--adopt-existing]
fclt sync [tool] [--dry-run] [--adopt-live]
fclt enable <selector> --for codex,claude
fclt disable <selector> --for codex,claude
fclt managed
fclt unmanage <tool>

setup codex-plugin is the narrow path for exposing the bundled fclt Codex plugin without entering managed mode. It writes only ~/plugins/fclt, the local marketplace entry, and the Codex plugin install/cache when Codex is available. Managed mode writes rendered output into tool homes. Read Managed mode before using it on an existing setup.

Writeback and evolution

fclt ai writeback add --kind <kind> --summary <text> --asset <selector>
fclt ai writeback list
fclt ai writeback show WB-00001
fclt ai writeback group --by asset
fclt ai writeback summarize --by kind

fclt ai evolve assess --asset <selector> --json
fclt ai evolve propose
fclt ai evolve list
fclt ai evolve show EV-00001
fclt ai evolve draft EV-00001
fclt ai evolve review EV-00001
fclt ai evolve accept EV-00001
fclt ai evolve reject EV-00001 --reason <text>
fclt ai evolve apply EV-00001
fclt ai evolve promote EV-00003 --to global --project

Use these to turn repeated work friction into reviewed capability changes. Plain list output shows the active root and scope so an empty project queue is not confused with the global queue. Use --global, --project, or --root when reviewing a specific scope, and use --json for automation.

Sources, Audit, And Updates

fclt search <query>
fclt install <source:item> [--as <name>] [--strict-source-trust]
fclt update [--apply]
fclt verify-source <name> [--json]
fclt sources list
fclt sources trust <source> [--note <text>]
fclt sources review <source> [--note <text>]
fclt sources block <source> [--note <text>]
fclt sources clear <source>
fclt audit [--non-interactive]
fclt self-update

self-update detects release-script, npm/Bun, and mise-managed npm installs. For mise installs it updates the global npm:facult pin and verifies the resolved fclt version through mise.

Use --strict-source-trust when installing or updating remote capability from catalogs.

Root Selection

Most commands accept the same root controls:

  • --global: use ~/.ai
  • --project: use the nearest repo-local .ai
  • --root /path/to/.ai: use an explicit canonical root
  • --scope merged|global|project: choose a discovery view
  • --source builtin|global|project: filter provenance in list/find/show/graph flows