Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 12 additions & 10 deletions apps/cli/docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,9 +63,10 @@ directory must already exist. Local mode does not clone, commit, push, or open a
credentials. Add `--dry-run` to validate the input and print the destination without writing.

This preview writes only the command-reference spec, not sidebar entries or JSON Schemas.
New commands still need an entry in the website's
[common-cli-sections.json](https://github.com/supabase/supabase/blob/master/apps/docs/spec/common-cli-sections.json)
to appear in the reference.
From `apps/cli`, `pnpm docs:spec <version>` generates the command-reference spec and
`pnpm docs:sidebar` generates the content for the website's
[common-cli-sections.json](https://github.com/supabase/supabase/blob/master/apps/docs/spec/common-cli-sections.json).
Copy the generated sidebar into that file so new commands appear in the reference.
Comment thread
mdonnalley marked this conversation as resolved.
Resolved

## Release Publishing

Expand Down Expand Up @@ -116,10 +117,11 @@ bun scripts/publish-schemas.ts --version <version> [--dry-run]

## Maintenance

When adding or changing a command or flag, update the matching entries in
`src/docs/docs-spec.tables.ts` — each table's doc comment says
when it applies: `TAGS`, `DEFAULT_OVERRIDES`, `REQUIRED`, `EXPERIMENTAL` (and
`_OPTIONAL`), `EXCLUDED` (whole commands), `EXCLUDED_FLAGS`, `ARG_OVERRIDES`,
`CHOICE_OVERRIDES`, `EXTRA_FLAGS`. The spec build fails on entries that no
longer resolve against the command tree, but new commands and flags must be
added by hand — nothing detects a missing entry for a new surface.
When adding or changing a command or flag, update the applicable argument overrides and extra
flags in `src/docs/docs-spec.tables.ts`; each table's doc comment says when it applies.
The spec build fails on entries that no longer resolve against the command tree, but it cannot
detect missing overrides for a new surface.
Each new top-level command needs `withSidebar({ category })`, using a category from
`DOCS_SIDEBAR_CATEGORIES` in `src/command-internal/command-sidebar.ts`.
Run `pnpm docs:sidebar` to regenerate the sidebar; the build rejects missing categories,
categories declared on subcommands, unused categories and titles longer than 50 characters.
1 change: 1 addition & 0 deletions apps/cli/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
"build:binary": "bun scripts/build-binary.ts",
"build:shim": "bun build src/shared/cli/bin.ts --outfile dist/supabase.js --target node",
"docs:spec": "bun scripts/generate-docs-spec.ts",
"docs:sidebar": "bun scripts/generate-docs-sidebar.ts",
"schemas:generate": "bun scripts/generate-schemas.ts",
"dev": "bun src/main.ts",
"gen:feedback-types": "pnpm dev -- gen types typescript --project-id xguihxuzqibwxjnimxev --schema public > src/shared/feedback/database.types.ts",
Expand Down
14 changes: 14 additions & 0 deletions apps/cli/scripts/generate-docs-sidebar.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
/**
* Emits the docs-site CLI sidebar (`common-cli-sections.json`) from the Effect command tree. Run as
* `bun scripts/generate-docs-sidebar.ts > common-cli-sections.json`.
*/
import { BunRuntime } from "@effect/platform-bun";
import { Console, Effect } from "effect";
import { rootCommand } from "../src/cli/root.ts";
import { buildDocsSidebar, stringifyDocsSidebar } from "../src/docs/docs-sidebar.ts";

BunRuntime.runMain(
Effect.try(() => stringifyDocsSidebar(buildDocsSidebar(rootCommand))).pipe(
Effect.flatMap(Console.log),
),
);
4 changes: 4 additions & 0 deletions apps/cli/scripts/generate-docs-spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import { Effect, Path } from "effect";
import process from "node:process";
import { readDocsContent } from "../src/docs/docs-spec.content.ts";
import { buildDocsSpec, stringifyDocsSpec } from "../src/docs/docs-spec.ts";
import { buildDocsSidebar } from "../src/docs/docs-sidebar.ts";
import { rootCommand } from "../src/cli/root.ts";

function resolveVersion(): string {
Expand All @@ -28,6 +29,9 @@ const content = await Effect.runPromise(
),
);

// The release publishes only the spec, so sidebar problems must fail it here.
buildDocsSidebar(rootCommand);

const spec = buildDocsSpec({
root: rootCommand,
version: resolveVersion(),
Expand Down
6 changes: 3 additions & 3 deletions apps/cli/scripts/publish-docs-spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -131,9 +131,9 @@ const main = Effect.gen(function* () {
"command tree or the content under `apps/cli/docs/` there rather than this",
"file.",
"",
"New commands also need an entry in `apps/docs/spec/common-cli-sections.json` —",
"without one a command's page is silently dropped from the docs site.",
"Sections fixes can be committed directly onto this branch — later releases",
"Generate `apps/docs/spec/common-cli-sections.json` content with `pnpm docs:sidebar`",
"from `apps/cli` in supabase/cli and copy it here; missing entries silently drop pages.",
"Sidebar fixes can be committed directly onto this branch; later releases",
Comment thread
mdonnalley marked this conversation as resolved.
Resolved
"add commits on top instead of rewriting it.",
].join("\n"),
autoMerge: false,
Expand Down
56 changes: 56 additions & 0 deletions apps/cli/src/command-internal/command-sidebar.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
import { Context, Option } from "effect";
import { Command } from "effect/cli";
/** Sidebar sections in display order; top-level commands pick one with `withSidebar`. */
export const DOCS_SIDEBAR_CATEGORIES = [
{ id: "general", title: "General" },
{ id: "testing", title: "Testing" },
{ id: "generate-types", title: "Generate Types" },
{ id: "database", title: "Database" },
{ id: "migrations", title: "Migrations" },
{ id: "seed", title: "Seed" },
{ id: "inspect", title: "Inspect" },
{ id: "logs", title: "Logs" },
{ id: "organizations", title: "Organizations" },
{ id: "projects", title: "Projects" },
{ id: "config", title: "Config" },
{ id: "branches", title: "Branches" },
{ id: "backups", title: "Backups" },
{ id: "edge-functions", title: "Edge Functions" },
{ id: "secrets", title: "Secrets" },
{ id: "storage", title: "Storage" },
{ id: "authentication", title: "Authentication" },
{ id: "custom-domains", title: "Custom Domains" },
{ id: "vanity-subdomains", title: "Vanity Subdomains" },
{ id: "encryption", title: "Encryption" },
{ id: "network-bans", title: "Network Bans" },
{ id: "network-restrictions", title: "Network Restrictions" },
{ id: "ssl-enforcement", title: "SSL Enforcement" },
{ id: "postgres-config", title: "Postgres Config" },
{ id: "sql-snippets", title: "SQL Snippets" },
{ id: "notebooks", title: "Notebooks" },
{ id: "services", title: "Services" },
{ id: "autocompletion-scripts", title: "Autocompletion Scripts" },
{ id: "telemetry", title: "Telemetry" },
{ id: "feedback", title: "Feedback" },
] as const;

export type DocsSidebarCategory = (typeof DOCS_SIDEBAR_CATEGORIES)[number]["id"];

/**
* Docs-site sidebar placement. Top-level commands declare a category, which their subcommands
* inherit; any command may override its sidebar title, which defaults to its short description.
*/
export type CommandSidebar =
| { readonly category: DocsSidebarCategory; readonly title?: string }
| { readonly title: string; readonly category?: never };

export class CommandSidebarAnnotation extends Context.Service<
CommandSidebarAnnotation,
CommandSidebar
>()("supabase/CommandSidebarAnnotation") {}

export const withSidebar = (sidebar: CommandSidebar) =>
Command.annotate(CommandSidebarAnnotation, sidebar);

export const readSidebar = (command: Command.Command.Any): Option.Option<CommandSidebar> =>
Context.getOption(command.annotations, CommandSidebarAnnotation);
2 changes: 2 additions & 0 deletions apps/cli/src/commands/backups/backups.command.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
import { withSidebar } from "../../command-internal/command-sidebar.ts";
import { Command } from "effect/cli";
import { backupsListCommand } from "./list/list.command.ts";
import { backupsRestoreCommand } from "./restore/restore.command.ts";

export const backupsCommand = Command.make("backups").pipe(
withSidebar({ category: "backups", title: "Manage physical backups" }),
Command.withDescription("Manage Supabase physical backups."),
Command.withShortDescription("Manage Supabase physical backups"),
Command.withSubcommands([backupsListCommand, backupsRestoreCommand]),
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/backups/list/list.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../../command-internal/command-sidebar.ts";
import type * as CliCommand from "effect/cli/Command";
import { Command } from "effect/cli";

Expand All @@ -20,6 +21,7 @@ const config = {
export type BackupsListFlags = CliCommand.Command.Config.Infer<typeof config>;

export const backupsListCommand = Command.make("list", config).pipe(
withSidebar({ title: "List available physical backups" }),
Command.withDescription("Lists available physical backups"),
Command.withShortDescription("Lists available physical backups"),
Command.withExamples([
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/bootstrap/bootstrap.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../command-internal/command-sidebar.ts";
import { Layer } from "effect";
import { Argument, Command } from "effect/cli";
import type * as CliCommand from "effect/cli/Command";
Expand Down Expand Up @@ -33,6 +34,7 @@ const config = {
export type BootstrapFlags = CliCommand.Command.Config.Infer<typeof config>;

export const bootstrapCommand = Command.make("bootstrap", config).pipe(
withSidebar({ category: "general", title: "Launch a quick start template" }),
Command.withDescription("Bootstrap a Supabase project from a starter template."),
Command.withShortDescription("Bootstrap a Supabase project from a starter template"),
withPermissions(
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/branches/branches.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../command-internal/command-sidebar.ts";
import { Command } from "effect/cli";
import { branchesListCommand } from "./list/list.command.ts";
import { branchesCreateCommand } from "./create/create.command.ts";
Expand All @@ -9,6 +10,7 @@ import { branchesDeleteCommand } from "./delete/delete.command.ts";
import { branchesDisableCommand } from "./disable/disable.command.ts";

export const branchesCommand = Command.make("branches").pipe(
withSidebar({ category: "branches" }),
Command.withDescription("Manage Supabase preview branches."),
Command.withShortDescription("Manage preview branches"),
Command.withSubcommands([
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/branches/get/get.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../../command-internal/command-sidebar.ts";
import { Argument, Command } from "effect/cli";
import type * as CliCommand from "effect/cli/Command";

Expand Down Expand Up @@ -57,6 +58,7 @@ const config = {
export type BranchesGetFlags = CliCommand.Command.Config.Infer<typeof config>;

export const branchesGetCommand = Command.make("get", config).pipe(
withSidebar({ title: "Show connection details for a preview branch" }),
Command.withDescription(
"Retrieve details of the specified preview branch.\n\nNote: For the main branch, password-dependent fields (POSTGRES_URL, POSTGRES_URL_NON_POOLING) are not populated because production database credentials are not retrievable via API.",
),
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/completion/bash/bash.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../../command-internal/command-sidebar.ts";
import { Command } from "effect/cli";
import type * as CliCommand from "effect/cli/Command";
import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts";
Expand All @@ -14,6 +15,7 @@ const config = {
export type CompletionBashFlags = CliCommand.Command.Config.Infer<typeof config>;

export const completionBashCommand = Command.make("bash", config).pipe(
withSidebar({ title: "Generate bash script" }),
Command.withDescription(
"Generate the autocompletion script for the bash shell.\n\n" +
"This script depends on the 'bash-completion' package.\n" +
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/completion/completion.command.ts
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
import { withSidebar } from "../../command-internal/command-sidebar.ts";
import { Command } from "effect/cli";
import { completionBashCommand } from "./bash/bash.command.ts";
import { completionFishCommand } from "./fish/fish.command.ts";
import { completionPowershellCommand } from "./powershell/powershell.command.ts";
import { completionZshCommand } from "./zsh/zsh.command.ts";

export const completionCommand = Command.make("completion").pipe(
withSidebar({ category: "autocompletion-scripts", title: "Generate autocompletion scripts" }),
Command.withDescription(
"Generate the autocompletion script for supabase for the specified shell.\n" +
"See each sub-command's help for details on how to use the generated script.",
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/completion/fish/fish.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../../command-internal/command-sidebar.ts";
import { Command } from "effect/cli";
import type * as CliCommand from "effect/cli/Command";
import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts";
Expand All @@ -14,6 +15,7 @@ const config = {
export type CompletionFishFlags = CliCommand.Command.Config.Infer<typeof config>;

export const completionFishCommand = Command.make("fish", config).pipe(
withSidebar({ title: "Generate fish script" }),
Command.withDescription(
"Generate the autocompletion script for the fish shell.\n\n" +
"To load completions in your current shell session:\n\n" +
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../../command-internal/command-sidebar.ts";
import { Command } from "effect/cli";
import type * as CliCommand from "effect/cli/Command";
import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts";
Expand All @@ -14,6 +15,7 @@ const config = {
export type CompletionPowershellFlags = CliCommand.Command.Config.Infer<typeof config>;

export const completionPowershellCommand = Command.make("powershell", config).pipe(
withSidebar({ title: "Generate powershell script" }),
Command.withDescription(
"Generate the autocompletion script for powershell.\n\n" +
"To load completions in your current shell session:\n\n" +
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/completion/zsh/zsh.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../../command-internal/command-sidebar.ts";
import { Command } from "effect/cli";
import type * as CliCommand from "effect/cli/Command";
import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts";
Expand All @@ -14,6 +15,7 @@ const config = {
export type CompletionZshFlags = CliCommand.Command.Config.Infer<typeof config>;

export const completionZshCommand = Command.make("zsh", config).pipe(
withSidebar({ title: "Generate zsh script" }),
Command.withDescription(
"Generate the autocompletion script for the zsh shell.\n\n" +
"If shell completion is not already enabled in your environment you will need\n" +
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/config/config.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../command-internal/command-sidebar.ts";
import { Command } from "effect/cli";
import { configConvertCommand } from "./convert/convert.command.ts";
import { configDiffCommand } from "./diff/diff.command.ts";
Expand All @@ -6,6 +7,7 @@ import { configPushCommand } from "./push/push.command.ts";
import { configValidateCommand } from "./validate/validate.command.ts";

export const configCommand = Command.make("config").pipe(
withSidebar({ category: "config" }),
Command.withDescription("Manage Supabase project configurations."),
Command.withShortDescription("Manage project configurations"),
Command.withSubcommands([
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/config/pull/pull.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../../command-internal/command-sidebar.ts";
import { Layer } from "effect";
import type * as CliCommand from "effect/cli/Command";
import { Command, Flag } from "effect/cli";
Expand Down Expand Up @@ -53,6 +54,7 @@ const configPullHandler = (flags: ConfigPullFlags) =>
);

export const configPullCommand = Command.make("pull", config).pipe(
withSidebar({ title: "Pull remote config into supabase/config.toml" }),
Command.withDescription(
"Writes configuration from a remote project or branch into the project config file. Prompts for confirmation before writing on an interactive TTY, unless --yes is set; --output-format json|stream-json skips the prompt entirely and takes its default answer, while a non-interactive text run still prints the prompt to stderr and reads one line from piped stdin (y/yes/n/no honored, empty takes the default, anything else declines) — use --dry-run to preview first.",
),
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/config/push/push.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../../command-internal/command-sidebar.ts";
import { Command } from "effect/cli";

import { withCliConfigFlags } from "../../../config/cli-config-flags.ts";
Expand Down Expand Up @@ -32,6 +33,7 @@ const configPushHandler = (flags: ConfigPushFlags) =>
);

export const configPushCommand = Command.make("push", config).pipe(
withSidebar({ title: "Push config from a local file" }),
Command.withDescription(
"Pushes the properties your local config file declares to the linked project or one of its branches. Properties the file does not declare are left unchanged; run `supabase config diff` to preview. Shows the exact diff for every changed resource, then asks once before anything is written (the default answer is no). Piped answers are not read: non-interactive and JSON runs need --yes or a SUPABASE_YES set in the shell. Run `supabase config diff` first to review the changes.",
),
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/db/advisors/advisors.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../../command-internal/command-sidebar.ts";
import { FlagDocumentation } from "../../../command-internal/flag-documentation.ts";
import { Command, Flag } from "effect/cli";
import type * as CliCommand from "effect/cli/Command";
Expand Down Expand Up @@ -41,6 +42,7 @@ const config = {
export type DbAdvisorsFlags = CliCommand.Command.Config.Infer<typeof config>;

export const dbAdvisorsCommand = Command.make("advisors", config).pipe(
withSidebar({ title: "Check database for security and performance issues" }),
Command.withDescription("Checks database for security and performance issues."),
Command.withShortDescription("Checks database for security and performance issues"),
Command.withHandler((flags) =>
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/db/db.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../command-internal/command-sidebar.ts";
import { Command } from "effect/cli";
import { dbDiffCommand } from "./diff/diff.command.ts";
import { dbDumpCommand } from "./dump/dump.command.ts";
Expand All @@ -14,6 +15,7 @@ import { dbRemoteCommand } from "./remote/remote.command.ts";
import { dbSchemaCommand } from "./schema/schema.command.ts";

export const dbCommand = Command.make("db").pipe(
withSidebar({ category: "database" }),
Command.withDescription("Manage Postgres databases."),
Command.withShortDescription("Manage databases"),
Command.withSubcommands([
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/db/lint/lint.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../../command-internal/command-sidebar.ts";
import { FlagDocumentation } from "../../../command-internal/flag-documentation.ts";
import { Command, Flag } from "effect/cli";
import type * as CliCommand from "effect/cli/Command";
Expand Down Expand Up @@ -43,6 +44,7 @@ const config = {
export type DbLintFlags = CliCommand.Command.Config.Infer<typeof config>;

export const dbLintCommand = Command.make("lint", config).pipe(
withSidebar({ title: "Lint local database" }),
Command.withDescription("Checks a database for typing error."),
Command.withShortDescription("Checks a database for typing error"),
Command.withExamples([
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/db/push/push.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../../command-internal/command-sidebar.ts";
import { Command, Flag } from "effect/cli";
import type * as CliCommand from "effect/cli/Command";

Expand Down Expand Up @@ -52,6 +53,7 @@ const config = {
export type DbPushFlags = CliCommand.Command.Config.Infer<typeof config>;

export const dbPushCommand = Command.make("push", config).pipe(
withSidebar({ title: "Push migration to remote database" }),
Command.withDescription(
"Push new migrations to a database. Vault secrets from the config file are updated before migrations unless --skip-vault is set.",
),
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/commands/db/reset/reset.command.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { withSidebar } from "../../../command-internal/command-sidebar.ts";
import { Command, Flag } from "effect/cli";
import type * as CliCommand from "effect/cli/Command";

Expand Down Expand Up @@ -43,6 +44,7 @@ const config = {
export type DbResetFlags = CliCommand.Command.Config.Infer<typeof config>;

export const dbResetCommand = Command.make("reset", config).pipe(
withSidebar({ title: "Reset local database" }),
Command.withDescription("Resets a database to current migrations."),
Command.withShortDescription("Resets a database to current migrations"),
Command.withExamples([
Expand Down
Loading
Loading