From 7d0b03eb8dc6d5f1bc1179cdbb40606b74d6ba40 Mon Sep 17 00:00:00 2001 From: Miguel Martinez Trivino Date: Sun, 20 Sep 2026 20:43:52 +0200 Subject: [PATCH 1/2] fix(cli): point trace init guide to the AI sessions docs Assisted-by: Claude Code Signed-off-by: Miguel Martinez Trivino Chainloop-Trace-Sessions: bfb0b23d-bd11-4f59-bde7-51ae13e60168 --- app/cli/cmd/trace_init.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/cli/cmd/trace_init.go b/app/cli/cmd/trace_init.go index 206dfc49d..e6b946620 100644 --- a/app/cli/cmd/trace_init.go +++ b/app/cli/cmd/trace_init.go @@ -214,7 +214,7 @@ The organization, project, workflow and require-trace values are saved to // traceDocsURL is the guide covering what this command set up and what can be // done with it, which is more than belongs in a command's own output. -const traceDocsURL = "https://docs.chainloop.dev/guides/chainloop-trace" +const traceDocsURL = "https://docs.chainloop.dev/ai-sessions" // writeTraceInitSummary reports what the repository was set up with. It goes to // stdout rather than through the logger because it is the command's result, From 85f743b29f413bbd1471ac7238d4c133701a2680 Mon Sep 17 00:00:00 2001 From: Miguel Martinez Trivino Date: Sun, 20 Sep 2026 21:38:28 +0200 Subject: [PATCH 2/2] docs(cli): generate the command reference as Markdown and link to it The reference is no longer published to the documentation site, so it is generated as plain Markdown rather than Mintlify MDX and the root command links to the file in this repository instead of the Enterprise Edition reference, which documents a different set of commands. Assisted-by: Claude Code Signed-off-by: Miguel Martinez Trivino Chainloop-Trace-Sessions: bfb0b23d-bd11-4f59-bde7-51ae13e60168 --- app/cli/cmd/root.go | 18 +++++++++++++++--- .../{cli-reference.mdx => cli-reference.md} | 8 ++------ app/cli/documentation/generate.go | 18 ++++++++++-------- docs/examples/policies/quickstart/README.md | 2 +- 4 files changed, 28 insertions(+), 18 deletions(-) rename app/cli/documentation/{cli-reference.mdx => cli-reference.md} (99%) mode change 100755 => 100644 diff --git a/app/cli/cmd/root.go b/app/cli/cmd/root.go index 8587910e7..1ec74304a 100644 --- a/app/cli/cmd/root.go +++ b/app/cli/cmd/root.go @@ -74,6 +74,12 @@ const ( trueString = "true" supportsFederatedAuthAnnotation = "supportsFederatedAuth" + + // cliReferenceURL is the generated reference for the commands in this + // repository. It is generated by app/cli/documentation and read there: the + // documentation site publishes the Enterprise Edition reference instead, so + // linking to it would send users to a page that documents other commands. + cliReferenceURL = "https://github.com/chainloop-dev/chainloop/blob/main/app/cli/documentation/cli-reference.md" ) var telemetryWg sync.WaitGroup @@ -104,8 +110,14 @@ func NewRootCmd(l zerolog.Logger) *cobra.Command { logger = l rootCmd := &cobra.Command{ - Use: appName, - Short: "Chainloop Command Line Interface", + Use: appName, + Short: "Chainloop Command Line Interface", + // The generated reference for these commands is kept in this repository + // rather than published to the documentation site, so the link points at + // the file itself. + Long: `Chainloop Command Line Interface + +Command reference: ` + cliReferenceURL, SilenceErrors: true, SilenceUsage: true, PersistentPreRunE: func(cmd *cobra.Command, _ []string) error { @@ -459,7 +471,7 @@ var ( // Posthog API key and endpoint are not sensitive information, they represent Chainloop's // Posthog instance. Both are overridable at build time with -X so anyone compiling the CLI // can point it at their own instance, and telemetry can be turned off entirely with - // DO_NOT_TRACK=1. See https://docs.chainloop.dev/command-line-reference/cli-telemetry. + // DO_NOT_TRACK=1. See https://docs.chainloop.dev/cli/telemetry. // // The endpoint is compiled in and has no runtime override, so an installed binary reports // wherever it was built to report. https://crb.chainloop.dev is therefore frozen on the diff --git a/app/cli/documentation/cli-reference.mdx b/app/cli/documentation/cli-reference.md old mode 100755 new mode 100644 similarity index 99% rename from app/cli/documentation/cli-reference.mdx rename to app/cli/documentation/cli-reference.md index 18995514d..7ca0e9c10 --- a/app/cli/documentation/cli-reference.mdx +++ b/app/cli/documentation/cli-reference.md @@ -1,10 +1,6 @@ ---- -title: Command Line Reference (OSS) ---- +# Command Line Reference (OSS) - -[The Enterprise Edition CLI](/command-line-reference/cli-ee-reference) provides additional platform management features, available with [paid plans](https://chainloop.dev/pricing). - +> [The Enterprise Edition CLI](https://docs.chainloop.dev/cli/reference) provides additional platform management features, available with [paid plans](https://chainloop.dev/pricing). Chainloop CLI is a command-line tool designed to streamline the process of crafting, managing, and storing software supply chain attestations. The CLI enables developers to generate and submit evidence-such as build artifacts, SBOMs, and vulnerability reports-directly from their CI/CD workflows, ensuring compliance with organizational policies without introducing friction into the development process. diff --git a/app/cli/documentation/generate.go b/app/cli/documentation/generate.go index 3459c4efc..df429c9b6 100644 --- a/app/cli/documentation/generate.go +++ b/app/cli/documentation/generate.go @@ -1,5 +1,5 @@ // -// Copyright 2025 The Chainloop Authors. +// Copyright 2025-2026 The Chainloop Authors. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -30,13 +30,12 @@ import ( "github.com/spf13/cobra/doc" ) -const fileHeader = `--- -title: Command Line Reference (OSS) ---- +// fileHeader is plain Markdown rather than MDX: this reference is read in the +// repository, not published to the documentation site, so it carries its own +// title instead of front matter and links out with absolute URLs. +const fileHeader = `# Command Line Reference (OSS) - -[The Enterprise Edition CLI](/command-line-reference/cli-ee-reference) provides additional platform management features, available with [paid plans](https://chainloop.dev/pricing). - +> [The Enterprise Edition CLI](https://docs.chainloop.dev/cli/reference) provides additional platform management features, available with [paid plans](https://chainloop.dev/pricing). Chainloop CLI is a command-line tool designed to streamline the process of crafting, managing, and storing software supply chain attestations. The CLI enables developers to generate and submit evidence-such as build artifacts, SBOMs, and vulnerability reports-directly from their CI/CD workflows, ensuring compliance with organizational policies without introducing friction into the development process. @@ -68,7 +67,10 @@ func main() { formatted := processFinalDocument(builder.String()) withHeader := fmt.Sprintf("%s%s", fileHeader, formatted) - err := os.WriteFile(filepath.Join(out, "cli-reference.mdx"), []byte(withHeader), 0600) + // The output directory is the argument in this file's go:generate directive, + // not anything a user of the CLI controls. + // nolint:gosec + err := os.WriteFile(filepath.Join(out, "cli-reference.md"), []byte(withHeader), 0600) if err != nil { log.Fatal(err) } diff --git a/docs/examples/policies/quickstart/README.md b/docs/examples/policies/quickstart/README.md index ed20e198f..3c39187d1 100644 --- a/docs/examples/policies/quickstart/README.md +++ b/docs/examples/policies/quickstart/README.md @@ -4,7 +4,7 @@ This quickstart guide walks you through creating and validating a basic Chainloo ## Documentation References -- **CLI Reference**: [chainloop policy develop commands](https://docs.chainloop.dev/command-line-reference/cli-reference#chainloop-policy) +- **CLI Reference**: [chainloop policy develop commands](https://docs.chainloop.dev/cli/reference#chainloop-policy) - **Policy Concepts**: [Understanding Chainloop Policies](https://docs.chainloop.dev/concepts/policies) - **Custom Policy Guide**: [Writing Custom Policies](https://docs.chainloop.dev/guides/custom-policies) - **Material Types**: [Available Material Types](https://docs.chainloop.dev/concepts/material-types#material-types)