docs/cli: Remove doc pages for removed src-cli commands by marcleblanc2 · Pull Request #1886 · sourcegraph/docs

marcleblanc2 · 2026-09-09T03:54:27Z

Why

The docs sync from sourcegraph/sourcegraph (doc/_generated.push.sh) does cp -R -L doc/cli/** _clone/docs/cli/ — it only adds and updates pages, never deletes. So when a command is removed from src-cli, its reference page lingers here forever. Replaying the sync against main shows zero drift in the 62 generated pages, but 36 files under docs/cli/references/ are never written by it.

This PR deletes the 28 that are stale. No redirects are added; none of these pages are linked from anywhere in the site.

Removed (28 files)

Command removed from src-cli

Pages	Removal
`extensions/{index,copy,delete,get,list,publish}`	sourcegraph/src-cli#1173 (extensions platform sunset)
`lsif`	sourcegraph/src-cli#1147 (→ `src code-intel upload`)
`scout`	sourcegraph/src-cli#1196
`sbom`, `signature`	sourcegraph/src-cli#1273 (SBOMs/signatures no longer published as of 7.0.2852; the how-tos already carry deprecation notices)
`admin`	sourcegraph/src-cli#1309 (built for the appliance, which never launched)
`validate`	sourcegraph/src-cli#1310

Command never shipped

prompts + 13 subcommand pages (#1155) documented sourcegraph/src-cli#1168, which was closed unmerged.

Stale duplicates shadowing generated pages

auth.mdx and codeowners.mdx collide with auth/index.mdx / codeowners/index.mdx: contentlayer flattens both to cli/references/auth, and allPosts.find returned the stale flat file. After this change /cli/references/auth and /cli/references/codeowners render the generated group pages (verified with contentlayer build).

Kept

search-jobs/{cancel,create,delete,get,list,logs,restart,results} — the subcommands exist, but src doc only emits a single search-jobs.md because searchJobsCommands isn't in the commanders map in cmd/src/doc.go. Fix belongs upstream.

Verification

npx tsc --noEmit passes
npx contentlayer build generates 493 docs; cli/references/auth and cli/references/codeowners now resolve to the index.mdx files
No remaining links to the deleted slugs anywhere in docs/ or src/

Follow-up (upstream)

To stop this recurring, _generated.push.sh should mirror docs/cli/references/ (delete-then-copy) instead of copying over it. Done in sourcegraph/sourcegraph#15529 (merge after sourcegraph/sourcegraph#15528 and #1889).

Amp threads

Stale command docs

vercel · 2026-09-09T03:54:33Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
sourcegraph-docs	Ready	Preview	Sep 11, 2026 2:05am UTC

Teams were removed in Sourcegraph 7.0; src-cli#1376 removes the command. No redirect, per the same call as #1886. Part of https://linear.app/sourcegraph/issue/FE-502 Amp-Thread-ID: https://ampcode.com/threads/T-01a08410-86ca-72be-9928-2810e837fae1 Co-authored-by: Amp <amp@ampcode.com>

The docs sync from sourcegraph/sourcegraph (doc/_generated.push.sh) only copies generated pages into docs/cli/; it never deletes, so pages for commands removed from src-cli have lingered. Remove them. Removed from src-cli: - extensions/* (src-cli#1173), lsif (#1147), scout (#1196), sbom + signature (#1273), admin (#1309), validate (#1310) Never shipped: - prompts/* documented src-cli#1168, which was closed unmerged Stale duplicates shadowing generated pages: - auth.mdx and codeowners.mdx collide with auth/index.mdx and codeowners/index.mdx on the same route; contentlayer picked the stale flat files, hiding the generated group pages. Amp-Thread-ID: https://ampcode.com/threads/T-01a08410-86ca-72be-9928-2810e837fae1 Co-authored-by: Amp <amp@ampcode.com>

Teams were removed in Sourcegraph 7.0; src-cli#1376 removes the command. No redirect, per the same call as #1886. Part of https://linear.app/sourcegraph/issue/FE-502 Amp-Thread-ID: https://ampcode.com/threads/T-01a08410-86ca-72be-9928-2810e837fae1 Co-authored-by: Amp <amp@ampcode.com>

Part of [FE-502](https://linear.app/sourcegraph/issue/FE-502). **Step 4 of 4** in a cross-repo stack, but **mergeable now** — it pre-seeds what the generated-docs sync will eventually write, so the live reference gets fixed without waiting on a src-cli release. ## Why The `src` CLI reference is generated by `src doc` and synced here by sourcegraph/sourcegraph's `sync/generated-docs` job. Two generator bugs (fixed in sourcegraph/src-cli#1375) left this reference incomplete: - `search-jobs`, `debug` and `snapshot` were never registered in the generator's `commanders` map, so each is a single page with only the group help; their 16 subcommands have no reference pages. (The 8 `search-jobs/*.mdx` pages here were hand-written by Travis Lyons in May 2025 to paper over this; nothing links to them.) - `index.mdx` lists only the 8 urfave/cli commands (`abc`, `api`, `auth`, `codeowners`, `login`, `orgs`, `users`, `version`) — `batch`, `repos`, `search`, `config`, etc. are missing from https://sourcegraph.com/docs/cli/references today. ## What - `index.mdx`: lists all 19 top-level commands. - `debug/{index,compose,kube,server}.mdx`, `snapshot/{index,databases,restore,summary,test,upload}.mdx`: new. - `search-jobs/index.mdx`: new; `search-jobs/{cancel,create,delete,get,list,logs,restart,results}.mdx`: hand-written pages replaced by generated ones (same usage text, plus a flags table; the `<p className="subtitle">` blurbs go away since the generator doesn't emit them). - Deleted `debug.mdx`, `search-jobs.mdx`, `snapshot.mdx`. - Deleted `teams.mdx` and dropped `teams` from `index.mdx`: teams were removed in Sourcegraph 7.0 and sourcegraph/src-cli#1376 removes the command, so the generator no longer emits this page. No redirect (same call as #1886). The sync job never deletes files, and in contentlayer routing a flat `foo.mdx` shadows `foo/index.mdx` (the same bug #1886 fixed for `auth.mdx`/`codeowners.mdx`), so these have to go by hand for the new index pages to be reachable. Content was produced by running the patched generator (src-cli `main` + #1375) and the same `tools/md2mdx` conversion the sync uses, so the sync PR that follows sourcegraph/sourcegraph#15528 should be a no-op for these paths. No redirects: the three deleted URLs (`/cli/references/{debug,search-jobs,snapshot}`) keep resolving, now to the new index pages. ## Stack 1. sourcegraph/src-cli#1375 — generator fix + tests; sourcegraph/src-cli#1376 (stacked) — remove `src teams`; sourcegraph/src-cli#1377 (stacked) — `src help` generated from registered commands, tests help == docs 2. src-cli 7.7.0 release (none since 7.6.0; blocks 3) 3. sourcegraph/sourcegraph#15528 — pin bump + `OUTPUT_FILES` + regenerate (draft until 2) 4. **this PR** 5. sourcegraph/sourcegraph#15529 — make the docs sync mirror `docs/cli/references/` so removed commands disappear automatically (merge after 3 and this PR) Related: #1886 (removed 28 stale pages for commands that no longer exist). ## Test plan `npx contentlayer build` → 528 documents; routes resolve to the intended files: ``` /cli/references/debug <- cli/references/debug/index.mdx /cli/references/search-jobs <- cli/references/search-jobs/index.mdx /cli/references/snapshot <- cli/references/snapshot/index.mdx ``` plus the 16 subcommand routes. (The `ERR_INVALID_ARG_TYPE`/clipanion stack trace during the build is pre-existing on `main`.) ## Amp threads - [Stale command docs](https://ampcode.com/threads/T-01a08410-86ca-72be-9928-2810e837fae1) --------- Co-authored-by: Amp <amp@ampcode.com>

marcleblanc2 force-pushed the cli-refs/remove-stale-command-pages branch from 3032bf5 to dd1683d Compare September 9, 2026 03:55

vercel Bot deployed to Preview September 9, 2026 03:57 View deployment

This was referenced Sep 9, 2026

fix/doc: Add missing commands to helper text sourcegraph/src-cli#1375

Open

docs/cli: Add missing doc pages for src-cli commands #1889

Merged

marcleblanc2 changed the title ~~cli: remove reference pages for commands that no longer exist in src-cli~~ cli: Remove reference pages for commands that no longer exist in src-cli Sep 9, 2026

marcleblanc2 changed the title ~~cli: Remove reference pages for commands that no longer exist in src-cli~~ docs/cli: Remove doc pages for removed src-cli commands Sep 9, 2026

pjlast approved these changes Sep 11, 2026

View reviewed changes

marcleblanc2 enabled auto-merge (squash) September 11, 2026 01:49

marcleblanc2 force-pushed the cli-refs/remove-stale-command-pages branch from dd1683d to 35b8dd1 Compare September 11, 2026 02:03

vercel Bot deployed to Preview September 11, 2026 02:05 View deployment

marcleblanc2 merged commit 2f8832a into main Sep 11, 2026
4 checks passed

marcleblanc2 deleted the cli-refs/remove-stale-command-pages branch September 11, 2026 02:05

Navigation Menu

Uh oh!

docs/cli: Remove doc pages for removed src-cli commands - #1886

docs/cli: Remove doc pages for removed src-cli commands#1886
marcleblanc2 merged 1 commit into
mainfrom
cli-refs/remove-stale-command-pages

marcleblanc2 commented Sep 9, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Sep 9, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

marcleblanc2 commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

Removed (28 files)

Kept

Verification

Follow-up (upstream)

Amp threads

Uh oh!

vercel Bot commented Sep 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

marcleblanc2 commented Sep 9, 2026 •

edited

Loading

vercel Bot commented Sep 9, 2026 •

edited

Loading