From c86254ba075cf51431686ba14f2e4b2f4d5d0cb1 Mon Sep 17 00:00:00 2001 From: Nathael Bonnal Date: Sun, 6 Sep 2026 15:21:24 +0200 Subject: [PATCH] docs(cli): add an index page for the commands section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit /en/cli/commands returned a 404: the seven command pages existed under it, but the directory itself resolved to nothing, so truncating the URL of any command page — the ordinary way to climb back to a section — hit the 404 page, and the section had no table of contents anywhere. The sidebar renders "Commands" as a plain group label, not a link, so nothing filled that role. Add commands/index.mdx, using the `permalink` frontmatter field the docs schema already supports to place it at the directory URL rather than at /en/cli/commands/index. It lists the seven commands grouped by what they are for, with a flat table for scanning. Link it from the CLI overview's "Next steps", so the section index is reachable from prose and not only from the sidebar. Closes ferriskey/ferriskey-cli#28 --- .../docs/cli/default/en/commands/index.mdx | 69 +++++++++++++++++++ .../content/docs/cli/default/en/overview.mdx | 5 +- 2 files changed, 73 insertions(+), 1 deletion(-) create mode 100644 apps/docs/src/content/docs/cli/default/en/commands/index.mdx diff --git a/apps/docs/src/content/docs/cli/default/en/commands/index.mdx b/apps/docs/src/content/docs/cli/default/en/commands/index.mdx new file mode 100644 index 0000000..596d707 --- /dev/null +++ b/apps/docs/src/content/docs/cli/default/en/commands/index.mdx @@ -0,0 +1,69 @@ +--- +title: Overview +description: "Index of every ferris-ctl command: what each one is for, and where its reference page lives." +icon: square-terminal +permalink: /en/cli/commands +order: 0 +--- + +# Commands + +`ferris-ctl` exposes seven top-level commands. Every one of them accepts the [global flags](/en/cli/overview#global-flags), and every one resolves where to connect, who you are, and which realm to act on before it sends anything — see [Authentication](/en/cli/authentication). + +## Connect and authenticate + +::::card-group{cols=3} +:::card{label="context" icon="lucide:server" href="/en/cli/commands/context"} +Named connection profiles storing a server URL, a client, and a default realm. Switch environments without retyping flags. +::: +:::card{label="login" icon="lucide:log-in" href="/en/cli/commands/login"} +Sign in with the OAuth 2.0 Device Authorization Grant and persist the session for every later command. +::: +:::card{label="logout" icon="lucide:log-out" href="/en/cli/commands/logout"} +Drop the stored session by deleting the credentials file. +::: +:::: + +## Administer a realm + +::::card-group{cols=3} +:::card{label="realm" icon="lucide:layers" href="/en/cli/commands/realm"} +Create, inspect, and delete realms — and import one from an external source. +::: +:::card{label="client" icon="lucide:box" href="/en/cli/commands/client"} +Create, inspect, and delete OAuth2 clients within a realm. +::: +:::card{label="user" icon="lucide:users" href="/en/cli/commands/user"} +Create, inspect, and delete users within a realm. +::: +:::: + +## Import + +::::card-group{cols=2} +:::card{label="source" icon="lucide:database" href="/en/cli/commands/source"} +Store reusable import sources, so credentials and URLs are not repeated on every import. +::: +:::card{label="Importing realms" icon="lucide:import" href="/en/cli/import/overview"} +The import guide: from a description file, a live Keycloak, or a live Zitadel instance. +::: +:::: + +## At a glance + +| Command | Purpose | +|---------|---------| +| [`context`](/en/cli/commands/context) | Manage connection contexts | +| [`realm`](/en/cli/commands/realm) | Manage realms | +| [`client`](/en/cli/commands/client) | Manage OAuth2 clients | +| [`user`](/en/cli/commands/user) | Manage users | +| [`source`](/en/cli/commands/source) | Manage reusable import sources | +| [`login`](/en/cli/commands/login) | Sign in via the OAuth 2.0 Device Authorization Grant | +| [`logout`](/en/cli/commands/logout) | Remove the stored login session | + +Each command carries its own help, down to the subcommand: + +```bash +ferris-ctl --help +ferris-ctl --help +``` diff --git a/apps/docs/src/content/docs/cli/default/en/overview.mdx b/apps/docs/src/content/docs/cli/default/en/overview.mdx index 25440dd..9f6b034 100644 --- a/apps/docs/src/content/docs/cli/default/en/overview.mdx +++ b/apps/docs/src/content/docs/cli/default/en/overview.mdx @@ -78,11 +78,14 @@ These flags are available on every command and override values stored in your co ## Next steps -::::card-group{cols=2} +::::card-group{cols=3} :::card{label="Getting Started" icon="lucide:rocket" href="/en/cli/getting-started"} Connect to a FerrisKey instance and run your first commands. ::: :::card{label="Authentication" icon="lucide:key-round" href="/en/cli/authentication"} Understand contexts, login sessions, and credential resolution. ::: +:::card{label="Commands" icon="lucide:square-terminal" href="/en/cli/commands"} +Every command, what it is for, and where its reference page is. +::: ::::