@sous-io/sous 0.2.14 → 0.2.16

package/docs/markdown/commands.md

@@ -41,6 +41,22 @@ Help has four spellings. `sous --help` prints the root screen; `sous repo add --
 `sous --version` prints the version alone, as `v1.2.3`; `sous --version --verbose` adds the package name, where
 it is installed, the platform and the Node build under it.
 
+## Flags that browse
+
+Every command that shows published versions takes the same two flags: `sous recipe list`, `sous recipe show`,
+`sous namespace list`, `sous namespace show`, `sous repo list`, `sous repo search` (and `sous search`) and
+`sous subscription list`. The flags combine.
+
+| Flag | What it does |
+|------|--------------|
+| `--latest` | Read each repository's index from upstream instead of the cache. `--remote` is the same flag. What it fetches is never written to the cache; a repository that cannot be reached is shown from the cache and named as not checked |
+| `--installed` | Show only what this project has installed, at the version its lockfile pins. A recipe whose repository is linked is marked `linked`, because builds read it from the checkout rather than the pinned version |
+
+Without either flag a browsing command reads only the cached indexes, so it works offline and fast.
+`sous recipe list --installed --latest` is the out-of-date view: each installed recipe with upstream's newest
+version beside the installed one. With `--installed`, `recipe show` and `namespace show` look the reference up
+among installed recipes only, and a reference to something published but not installed is an error saying so.
+
 Every topic answers to both spellings of its name: `repo` and `repos`, `subscription` and `subscriptions`,
 `namespace` and `namespaces`, `recipe` and `recipes`, `lock` and `locks`, `vars` and `var`, `config` and
 `configs`. Three commands also answer to one word: `sous search`, `sous subscribe` and `sous unsubscribe`.
@@ -79,6 +95,12 @@ and the command you want almost always. Takes `--dry-run`.
 - `--strict`: fail on any compilation error rather than reporting it and continuing.
 - `-w, --watch`: rebuild on every change to a source file, a config layer or a linked checkout.
 
+Before it compiles, a build lists each recipe this project uses that has a newer version within the range
+declared for it, beside the version pinned. It moves no pin; only always-pull moves one. The build reads upstream
+for this at most once per freshness window (`store.freshnessSeconds`, five minutes by default), gives a
+repository three seconds to answer, and otherwise answers from the cached index without a word about the
+failed check.
+
 Example: `sous build --rebuild`
 
 ### `sous compile`
@@ -103,8 +125,10 @@ Example: `sous launch claude --continuous`
 
 ### `sous search TEXT`
 Searches the recipes every trusted repository publishes, by name or description; reads the cached indexes only,
-so it works offline. `--limit <n>` sets how many matches to show, defaulting to 25. Also spelled
-`sous repo search`. Example: `sous search task --limit 50`
+so it works offline. `--limit <n>` sets how many matches to show, defaulting to 25. Takes the
+[browsing flags](#flags-that-browse): `--latest` searches the indexes upstream serves, and `--installed` searches
+only installed recipes and adds an Installed column. Also spelled `sous repo search`.
+Example: `sous search task --limit 50`
 
 ### `sous help [COMMAND]`
 Prints the help for sous, or for one command or topic. Works from any directory, including one with no config
@@ -155,7 +179,9 @@ held, the files the next build prunes, and the linked checkout if one points at
 ### `sous repo list`
 Lists the repositories this project trusts, with the provider, where the entry came from, whether it is linked,
 how many recipes it publishes (`not fetched` until its index has been downloaded) and its URL. `--verbose` adds
-the namespaces each one publishes, on a line under its row.
+the namespaces each one publishes, on a line under its row. Takes the [browsing flags](#flags-that-browse):
+`--installed` keeps only the repositories something is installed from and names each installed recipe and
+version on a line under its row.
 
 ```term
 $ sous repo list
@@ -165,7 +191,8 @@ $ sous repo list
 ```
 
 ### `sous repo search TEXT`
-Same command as `sous search`, under its own topic; takes `--limit <n>`. Example: `sous repo search browser`
+Same command as `sous search`, under its own topic; takes `--limit <n>` and the
+[browsing flags](#flags-that-browse). Example: `sous repo search browser --installed`
 
 ### `sous repo gc`
 Collects the machine-wide recipe store down to its size cap. `--max-bytes <n>` collects to that cap instead of
@@ -177,10 +204,30 @@ Points a repository at a working copy on this machine instead of a published ver
 clones it into `.sous/repos` and links the clone; a name or URL with a `PATH` links the checkout at that path; a
 path alone links that checkout where it is, adding the repository first if needed. Takes `--dry-run`.
 
-- `--global`: link for every project on this machine, sharing one checkout.
-- `-y, --yes`: answer the trust question a not-yet-added repository raises (also `--trust`).
-
-Example: `sous repo link sous-recipes ~/Projects/sous-recipes`
+A checkout that was already on disk is fetched (a fetch changes none of its files or branches) and compared with
+upstream: its branch, whether that branch is merged into the default branch, and how many commits it is behind.
+When upstream cannot be reached within a few seconds, a warning gives git's reason and says since when the
+checkout may have diverged, and the link is still recorded. Nothing else changes the checkout unless a flag
+asks for it; git carries out each step, and a step git refuses stops the command with git's own message.
+
+- `--global`: link for every project on this machine, sharing one checkout. Changing that checkout's branch
+  says it affects every project that links it.
+- `--branch <name>`: switch to an existing branch, fetching it from upstream first when it is not local.
+- `--create-branch <name>`: create a new branch and switch to it; git refuses a name that already exists.
+- `--generate-branch`: the same, with the generated name `sous/edit-<YYYYMMDD>-<HHMM>`, which is printed.
+- `--from <branch>`: the base of the new branch, fetched first. Defaults to the repository's default branch,
+  not whatever is checked out, and needs `--create-branch` or `--generate-branch`.
+- `--latest`: make the branch being worked from (the `--branch` target, the `--from` base, or else the default
+  branch) match upstream's, leaving every other branch alone. What that would discard (uncommitted changes and
+  local commits upstream lacks) is listed first, with one question; it fails when the fetch fails.
+- `-y, --yes`: answer the trust question a not-yet-added repository raises and the question `--latest` asks
+  (also `-f`, `--force`, `--trust`).
+
+`--branch`, `--create-branch` and `--generate-branch` exclude each other; each flag works on a checkout linked
+by path, too.
+
+Example: `sous repo link sous-recipes ~/Projects/sous-recipes`, or `sous repo link sous-recipes
+--generate-branch --latest --yes`
 
 ### `sous repo unlink REPO`
 Stops reading a repository from a working copy and goes back to published versions; `REPO` is the short name as
@@ -245,13 +292,16 @@ Removes a subscription and everything only it brought in, then rebuilds so those
 
 ### `sous subscription list`
 Lists the subscriptions this project declares, switched-off ones included, with the range each resolves within,
-the versions the lockfile pins, where it came from and whether it is on. Reads the config and the lockfile only.
-Example: `sous subscription list`
+the versions the lockfile pins, the latest version each of those recipes has published, where it came from and
+whether it is on. Reads the config, the lockfile and the cached indexes only. Takes the
+[browsing flags](#flags-that-browse): `--latest` reads the latest versions from upstream, and `--installed` keeps
+only the subscriptions that have pinned something. Example: `sous subscription list --latest`
 
 ## namespace
 
 `namespace` reads the cached indexes and the lockfile, so it works offline. A trusted repository whose index has
-never been fetched is named at the end of a listing, not left out.
+never been fetched is named at the end of a listing, not left out. Both commands take the
+[browsing flags](#flags-that-browse); with `--installed` the recipe count is the number installed.
 
 ### `sous namespace list`
 Lists every namespace the trusted repositories publish, how many recipes each holds, and how much of it this
@@ -264,11 +314,12 @@ Example: `sous namespace show sous-recipes:core`
 
 ## recipe
 
-Browses the recipes the trusted repositories publish; like `namespace`, it works offline.
+Browses the recipes the trusted repositories publish; like `namespace`, it works offline, and both commands take
+the [browsing flags](#flags-that-browse).
 
 ### `sous recipe list`
 Lists the recipes the trusted repositories publish, across every namespace, with the same per-recipe columns
-`namespace show` prints. Example: `sous recipe list`
+`namespace show` prints. Example: `sous recipe list --installed --latest`
 
 ### `sous recipe show REF`
 Describes one recipe completely: its repository and location, every published version, its dependencies as

package/docs/markdown/repositories-authoring.md

@@ -289,6 +289,59 @@ Run 'sous repo unlink my-recipes' to go back to published versions.
 `sous repo unlink` removes the map entry and nothing else: the checkout stays where it is, and its path is
 printed so you can delete it. Unlinking a name linked in the other scope says which scope holds it.
 
+### How a checkout compares with upstream
+
+A link says which checkout to read, not why, so `sous repo link` never changes a checkout on its own. When the
+checkout was already on disk (a clone reused from an earlier link, or one you named by path), it runs a short
+`git fetch`, which updates only the remote-tracking refs, and reports what it found. The part of the output that
+reports it looks like this:
+
+```term
+$ sous repo link my-recipes
+    Branch                 : lc/my-change
+    Compared with          : origin/main
+    Merged into origin/main: yes
+    Behind origin/main     : 12 commits
+```
+
+A branch that is merged and behind has usually been released already, and the checkout is building from an older
+state than upstream's. When the fetch fails or takes longer than a few seconds, the link is still recorded, and
+a warning gives git's reason and says since when the checkout may have diverged (the last time it was fetched).
+The fetch is skipped for a checkout sous has just cloned, and a checkout with no `origin` remote says it has no
+upstream to compare with.
+
+### Choosing the branch
+
+Every change to the checkout is a flag, and git carries each one out. When git refuses a step (a conflict with
+uncommitted changes, a branch that already exists, one that does not), the command stops and shows git's message
+under a line naming the step. Each flag works on a checkout linked by path, too.
+
+```bash
+sous repo link my-recipes --branch lc/their-change     # read from an existing branch
+sous repo link my-recipes --create-branch my-change    # start a new branch
+sous repo link my-recipes --generate-branch            # start one named sous/edit-<YYYYMMDD>-<HHMM>
+sous repo link my-recipes --generate-branch --from next  # start it from another branch
+sous repo link my-recipes --latest                     # bring the default branch up to upstream's
+```
+
+- `--branch <name>` switches with `git switch`, which also checks out a branch that exists only upstream. A clone
+  sous makes holds only the default branch, so a branch that is not local is fetched first and added to the
+  branches `origin` is fetched for.
+- `--create-branch <name>` and `--generate-branch` create a new branch and switch to it; the generated name is
+  printed. The new branch starts from upstream's copy of `--from`, which defaults to the repository's default
+  branch rather than whatever is checked out, so a new branch never silently stacks on an old, already-merged
+  one. `--from` is an error without one of the two.
+- `--branch`, `--create-branch` and `--generate-branch` exclude each other.
+- `--latest` means upstream's latest version of what you are working from: the `--branch` target, the `--from`
+  base, or otherwise the default branch. It fetches that branch, switches to it and makes it match upstream's,
+  and leaves every other branch alone. Making a branch match upstream discards local work without git warning
+  about it, so this is the one place sous checks for itself: uncommitted changes to tracked files and local
+  commits upstream lacks are listed first, with one question. `--yes` answers it, and a run with no terminal
+  fails naming that flag. When the fetch fails, `--latest` fails, with git's reason.
+
+A `--global` link's checkout is shared by every project on the machine that links the repository globally, so
+changing its branch says it affects all of them.
+
 ## Contribute to someone else's repository
 
 `sous repo submit` proposes your committed changes to a repository's maintainers; it never publishes and never

package/docs/markdown/repositories-consuming.md

@@ -52,6 +52,19 @@ sous namespace show workflow   # one namespace and the recipes in it
 sous recipe list               # every recipe, latest version, pinned version, subscribed
 ```
 
+The cache can be behind what a repository has published since. Every one of these commands, plus
+`sous recipe show`, `sous repo list` and `sous subscription list`, takes two flags that combine:
+
+- `--latest` (also `--remote`) reads each index from upstream instead. Nothing it fetches is
+  written to the cache; only a command that resolves versions changes what the cache holds. A
+  repository that cannot be reached is shown from the cache and named as not checked.
+- `--installed` narrows the listing to what this project has installed, at the version the
+  lockfile pins. A recipe from a linked repository is marked `linked`, because builds read it from
+  the checkout instead of that version.
+
+`sous recipe list --installed --latest` is the out-of-date view: every installed recipe, with
+upstream's newest version beside the installed one.
+
 Read `sous recipe show` before subscribing: every published version, what it depends on (as
 declared, beside the version the index resolved it to), and its questions and files once it has
 them here.
@@ -201,7 +214,8 @@ $ sous subscription list
 
 A namespace subscription names every recipe it holds, each with the version the lockfile pins. A
 subscription that has never been built has nothing pinned yet, and its cell reads `pinned on first
-build` instead.
+build` instead. The `Latest version` column beside it is read from the cache, or from upstream with
+`--latest`.
 
 `sous repo list` shows each trusted repository with its provider, origin, whether it is linked, its
 recipe count and its URL; `--verbose` adds a `Namespaces:` line under each row. `sous lock show`
@@ -278,6 +292,23 @@ happens after that check, not how often it happens: a repository or subscription
 `alwaysPull` takes a newer in-range version rather than the locked one; set it with
 `--always-pull`, or on either entry in the config.
 
+Every other repository the lockfile pins from is checked on the same window, only to tell you what
+is newer. A build lists each recipe with a newer version inside the range declared for it, beside
+the version it pins, and moves nothing:
+
+```term
+$ sous build
+▶ Newer versions published:
+
+    workflow/qa-variables: 0.2.0 this project pins 0.1.0
+
+  This version is within the range declared for the recipe. No pin was changed, so this build
+  uses the pinned version.
+```
+
+That check waits at most three seconds for a repository, and a check that fails or runs out of
+time is not mentioned: the cached index answers instead, and the build carries on.
+
 The store is machine-wide and disposable, because everything in it is re-fetchable from a
 lockfile's pins. `sous repo gc` collects it back to its size cap, evicting least recently used
 entries first, and protects everything this project's lockfile pins whatever that does to the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",

package/recipes/core/sous-skills/sous.recipe.yaml

@@ -11,7 +11,7 @@ formatVersion: 1
 
 namespace: core
 name: sous-skills
-version: 0.2.14
+version: 0.2.16
 
 description: >-
   The skills that teach an agent what sous is and how it works: which files sous

package/src/commands/namespace/list.ts

@@ -3,17 +3,25 @@
  *
  * Shows every namespace published by the repositories this project trusts, how
  * many recipes each one holds, and how much of it the project subscribes to. It
- * reads only the indexes sous already has on disk, so it works offline; a
- * repository whose index has never been fetched is named at the end rather than
- * being silently left out.
+ * reads only the indexes sous already has on disk by default, so it works
+ * offline; a repository whose index has never been fetched is named at the end
+ * rather than being silently left out. `--latest` reads the indexes from
+ * upstream instead, without saving them, and `--installed` narrows the listing
+ * to the namespaces the lockfile pins a recipe from.
  */
 
 import { BaseCommand } from "../../base-command.js";
 import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
-import { catalogContextFor } from "../../lib/repos/catalog-inputs.js";
-import { listNamespaces } from "../../lib/repos/catalog.js";
-import { INDENT, describeCoverage } from "../../lib/repos/catalog-display.js";
+import { loadCatalogContext } from "../../lib/repos/catalog-inputs.js";
+import { listNamespaces, narrowToInstalled } from "../../lib/repos/catalog.js";
+import {
+  INDENT,
+  describeCoverage,
+  describeIndexSource,
+  printBrowsingNotes,
+} from "../../lib/repos/catalog-display.js";
 import { renderTable, type TableColumn } from "../../utils/table.js";
+import { browsingFlags } from "../../utils/flags.js";
 import {
   blankLine,
   footer,
@@ -53,19 +61,28 @@ export default class NamespaceList extends BaseCommand {
    */
   static aliases = ["namespaces:list"];
 
-  static examples = ["<%= config.bin %> namespace list"];
+  static examples = [
+    "<%= config.bin %> namespace list",
+    "<%= config.bin %> namespace list --installed",
+  ];
 
-  static flags = { ...BaseCommand.baseFlags };
+  static flags = { ...BaseCommand.baseFlags, ...browsingFlags() };
 
   async run(): Promise<void> {
-    await this.parse(NamespaceList);
+    const { flags } = await this.parse(NamespaceList);
 
     showCommandVars({
       Project: this.projectLabel,
       Config: this.configContext.configPath,
+      Reading: describeIndexSource(flags.latest),
+      ...(flags.installed ? { Showing: "only what this project has installed" } : {}),
     });
 
-    heading("Namespaces in the repositories this project trusts");
+    heading(
+      flags.installed
+        ? "Namespaces this project has installed recipes from"
+        : "Namespaces in the repositories this project trusts"
+    );
 
     const service = subscriptionServiceFor({
       configContext: this.configContext,
@@ -73,13 +90,21 @@ export default class NamespaceList extends BaseCommand {
       shellEnv: this.shellEnv,
     });
 
-    const { inputs, notFetched } = catalogContextFor({
+    const { inputs, notFetched, notChecked } = await loadCatalogContext({
       service,
       sousDir: this.configContext.sousDir,
       settings: this.settings,
+      latest: flags.latest,
     });
 
-    const listings = listNamespaces(inputs);
+    // Narrowed to what is installed, a namespace's recipe count is the number
+    // of its recipes the project has installed, and the column says so.
+    const listings = listNamespaces(flags.installed ? narrowToInstalled(inputs) : inputs);
+    const columns = flags.installed
+      ? COLUMNS.map((column) =>
+          column.key === "recipes" ? { ...column, header: "Installed" } : column
+        )
+      : COLUMNS;
 
     blankLine();
 
@@ -88,7 +113,9 @@ export default class NamespaceList extends BaseCommand {
         inputs.repos.length === 0
           ? "Sous has read no repository index for this project, so there are no " +
             "namespaces to show."
-          : "The repositories this project trusts publish no namespaces."
+          : flags.installed
+            ? "This project has installed no recipe from the repositories it trusts."
+            : "The repositories this project trusts publish no namespaces."
       );
     } else {
       const rows = listings.map((entry) => ({
@@ -99,18 +126,12 @@ export default class NamespaceList extends BaseCommand {
         description: entry.description ?? "no description published",
       }));
 
-      for (const line of renderTable(COLUMNS, rows, { indent: INDENT })) {
+      for (const line of renderTable(columns, rows, { indent: INDENT })) {
         log(indent(line, INDENT));
       }
     }
 
-    if (notFetched.length > 0) {
-      blankLine();
-      paragraph(
-        `These repositories are trusted and their index has not been fetched yet, so ` +
-          `nothing in them is listed: ${notFetched.join(", ")}.`
-      );
-    }
+    printBrowsingNotes({ notFetched, notChecked });
 
     footer();
   }

package/src/commands/namespace/show.ts

@@ -4,23 +4,28 @@
  * Shows one namespace in full: the repository publishing it, what that
  * repository says it is for, how much of it this project subscribes to, and
  * every recipe in it with its latest version, its pinned version and its own
- * subscription state. It reads only the indexes sous already has on disk.
+ * subscription state. It reads only the indexes sous already has on disk,
+ * unless `--latest` asks it to read upstream (which saves nothing); `--installed`
+ * narrows the recipes to the ones the lockfile pins.
  */
 
 import { Args } from "@oclif/core";
 import { BaseCommand } from "../../base-command.js";
 import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
-import { catalogContextFor } from "../../lib/repos/catalog-inputs.js";
-import { describeNamespace } from "../../lib/repos/catalog.js";
+import { loadCatalogContext } from "../../lib/repos/catalog-inputs.js";
+import { describeInstalled, describeNamespace } from "../../lib/repos/catalog.js";
 import {
   INDENT,
-  RECIPE_COLUMNS,
   describeCoverage,
+  describeIndexSource,
   factIf,
+  printBrowsingNotes,
   printFacts,
+  recipeColumns,
   recipeRows,
 } from "../../lib/repos/catalog-display.js";
 import { renderTable } from "../../utils/table.js";
+import { browsingFlags } from "../../utils/flags.js";
 import {
   blankLine,
   footer,
@@ -53,15 +58,17 @@ export default class NamespaceShow extends BaseCommand {
     }),
   };
 
-  static flags = { ...BaseCommand.baseFlags };
+  static flags = { ...BaseCommand.baseFlags, ...browsingFlags() };
 
   async run(): Promise<void> {
-    const { args } = await this.parse(NamespaceShow);
+    const { args, flags } = await this.parse(NamespaceShow);
 
     showCommandVars({
       Project: this.projectLabel,
       Config: this.configContext.configPath,
       Namespace: args.ref,
+      Reading: describeIndexSource(flags.latest),
+      ...(flags.installed ? { Showing: "only what this project has installed" } : {}),
     });
 
     const service = subscriptionServiceFor({
@@ -70,13 +77,16 @@ export default class NamespaceShow extends BaseCommand {
       shellEnv: this.shellEnv,
     });
 
-    const { inputs } = catalogContextFor({
+    const { inputs, notChecked } = await loadCatalogContext({
       service,
       sousDir: this.configContext.sousDir,
       settings: this.settings,
+      latest: flags.latest,
     });
 
-    const detail = describeNamespace(inputs, args.ref);
+    const detail = flags.installed
+      ? describeInstalled(inputs, args.ref, describeNamespace, "namespace")
+      : describeNamespace(inputs, args.ref);
 
     heading(`The namespace ${detail.namespace}`);
     blankLine();
@@ -85,7 +95,10 @@ export default class NamespaceShow extends BaseCommand {
       { label: "Repository", lines: [detail.repo] },
       ...factIf("Location", detail.repoUrl),
       ...factIf("About", detail.description),
-      { label: "Recipes", lines: [String(detail.recipes.length)] },
+      {
+        label: flags.installed ? "Installed recipes" : "Recipes",
+        lines: [String(detail.recipes.length)],
+      },
       { label: "Subscribed", lines: [describeCoverage(detail.subscribed)] },
     ]);
 
@@ -99,12 +112,19 @@ export default class NamespaceShow extends BaseCommand {
       return;
     }
 
-    for (const line of renderTable(RECIPE_COLUMNS, recipeRows(detail.recipes), {
-      indent: INDENT,
-    })) {
+    for (const line of renderTable(
+      recipeColumns({ installed: flags.installed }),
+      recipeRows(detail.recipes),
+      { indent: INDENT }
+    )) {
       log(indent(line, INDENT));
     }
 
+    printBrowsingNotes({
+      notChecked: notChecked.filter((name) => name === detail.repo),
+      anyLinked: detail.recipes.some((entry) => entry.linkedPath !== undefined),
+    });
+
     footer();
   }
 }

package/src/commands/recipe/list.ts

@@ -3,21 +3,26 @@
  *
  * Shows every recipe the repositories this project trusts publish, with the
  * latest published version, the version this project pins, and whether it is
- * subscribed. It reads only the indexes sous already has on disk, so it works
- * offline; a repository whose index has never been fetched is named at the end
- * rather than being silently left out.
+ * subscribed. By default it reads only the indexes sous already has on disk, so
+ * it works offline; a repository whose index has never been fetched is named at
+ * the end rather than being silently left out. `--latest` reads the indexes
+ * from upstream instead, without saving them, and `--installed` narrows the
+ * listing to what the lockfile pins.
  */
 
 import { BaseCommand } from "../../base-command.js";
 import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
-import { catalogContextFor } from "../../lib/repos/catalog-inputs.js";
-import { listRecipes } from "../../lib/repos/catalog.js";
+import { loadCatalogContext } from "../../lib/repos/catalog-inputs.js";
+import { listRecipes, narrowToInstalled } from "../../lib/repos/catalog.js";
 import {
   INDENT,
-  RECIPE_COLUMNS,
+  describeIndexSource,
+  printBrowsingNotes,
+  recipeColumns,
   recipeRows,
 } from "../../lib/repos/catalog-display.js";
 import { renderTable } from "../../utils/table.js";
+import { browsingFlags } from "../../utils/flags.js";
 import {
   blankLine,
   footer,
@@ -37,19 +42,28 @@ export default class RecipeList extends BaseCommand {
    */
   static aliases = ["recipes:list"];
 
-  static examples = ["<%= config.bin %> recipe list"];
+  static examples = [
+    "<%= config.bin %> recipe list",
+    "<%= config.bin %> recipe list --installed --latest",
+  ];
 
-  static flags = { ...BaseCommand.baseFlags };
+  static flags = { ...BaseCommand.baseFlags, ...browsingFlags() };
 
   async run(): Promise<void> {
-    await this.parse(RecipeList);
+    const { flags } = await this.parse(RecipeList);
 
     showCommandVars({
       Project: this.projectLabel,
       Config: this.configContext.configPath,
+      Reading: describeIndexSource(flags.latest),
+      ...(flags.installed ? { Showing: "only what this project has installed" } : {}),
     });
 
-    heading("Recipes in the repositories this project trusts");
+    heading(
+      flags.installed
+        ? "Recipes this project has installed"
+        : "Recipes in the repositories this project trusts"
+    );
 
     const service = subscriptionServiceFor({
       configContext: this.configContext,
@@ -57,13 +71,14 @@ export default class RecipeList extends BaseCommand {
       shellEnv: this.shellEnv,
     });
 
-    const { inputs, notFetched } = catalogContextFor({
+    const { inputs, notFetched, notChecked } = await loadCatalogContext({
       service,
       sousDir: this.configContext.sousDir,
       settings: this.settings,
+      latest: flags.latest,
     });
 
-    const listings = listRecipes(inputs);
+    const listings = listRecipes(flags.installed ? narrowToInstalled(inputs) : inputs);
 
     blankLine();
 
@@ -72,23 +87,25 @@ export default class RecipeList extends BaseCommand {
         inputs.repos.length === 0
           ? "Sous has read no repository index for this project, so there are no " +
             "recipes to show."
-          : "The repositories this project trusts publish no recipes."
+          : flags.installed
+            ? "This project has installed no recipe from the repositories it trusts."
+            : "The repositories this project trusts publish no recipes."
       );
     } else {
-      for (const line of renderTable(RECIPE_COLUMNS, recipeRows(listings), {
-        indent: INDENT,
-      })) {
+      for (const line of renderTable(
+        recipeColumns({ installed: flags.installed }),
+        recipeRows(listings),
+        { indent: INDENT }
+      )) {
         log(indent(line, INDENT));
       }
     }
 
-    if (notFetched.length > 0) {
-      blankLine();
-      paragraph(
-        `These repositories are trusted and their index has not been fetched yet, so ` +
-          `nothing in them is listed: ${notFetched.join(", ")}.`
-      );
-    }
+    printBrowsingNotes({
+      notFetched,
+      notChecked,
+      anyLinked: listings.some((entry) => entry.linkedPath !== undefined),
+    });
 
     footer();
   }