chore: update CLI help docs

cmd/drift.go

@@ -1,12 +1,21 @@
 package cmd
 
-import "github.com/spf13/cobra"
+import (
+	_ "embed"
+
+	"github.com/Use-Tusk/tusk-cli/internal/utils"
+	"github.com/spf13/cobra"
+)
 
 const configFlagUsage = "config file (default is .tusk/config.yaml)"
 
+//go:embed short_docs/drift/drift_overview.md
+var driftOverviewContent string
+
 var driftCmd = &cobra.Command{
 	Use:   "drift",
 	Short: "Tusk Drift commands",
+	Long:  utils.RenderMarkdown(driftOverviewContent),
 }
 
 func init() {

cmd/list.go

@@ -17,10 +17,10 @@ import (
 	"github.com/Use-Tusk/tusk-cli/internal/utils"
 )
 
-//go:embed short_docs/list.md
+//go:embed short_docs/drift/drift_list.md
 var listContent string
 
-//go:embed short_docs/filter.md
+//go:embed short_docs/drift/drift_filter.md
 var filterContent string
 
 var listJSON bool

cmd/root.go

@@ -30,12 +30,12 @@ var (
 )
 
 //go:embed short_docs/overview.md
-var overviewContent string
+var tuskOverviewContent string
 
 var rootCmd = &cobra.Command{
 	Use:   "tusk",
 	Short: "Tusk CLI - Unit test automation and API test record/replay system",
-	Long:  utils.RenderMarkdown(overviewContent),
+	Long:  utils.RenderMarkdown(tuskOverviewContent),
 	Run: func(cmd *cobra.Command, args []string) {
 		showASCIIArt()
 	},

cmd/run.go

@@ -57,7 +57,7 @@ var (
 	validateSuite                bool
 )
 
-//go:embed short_docs/run.md
+//go:embed short_docs/drift/drift_run.md
 var runContent string
 
 var runCmd = &cobra.Command{

cmd/setup.go

@@ -17,7 +17,7 @@ import (
 	"golang.org/x/term"
 )
 
-//go:embed short_docs/setup.md
+//go:embed short_docs/drift/drift_setup.md
 var setupContent string
 
 var (

cmd/short_docs/filter.md → cmd/short_docs/drift/drift_filter.md

@@ -8,9 +8,9 @@ Comma-separated, values are regex.
 Examples:
 
 ```bash
-tusk <list/run> -f 'type=GRAPHQL,op=^GetUser$'
-tusk <list/run> -f 'method=POST,path=/checkout'
-tusk <list/run> -f 'file=2025-09-24.*trace.*\\.jsonl'
+tusk drift <list/run> -f 'type=GRAPHQL,op=^GetUser$'
+tusk drift <list/run> -f 'method=POST,path=/checkout'
+tusk drift <list/run> -f 'file=2025-09-24.*trace.*\\.jsonl'
 ```
 
 See <https://github.com/Use-Tusk/tusk-cli/blob/main/docs/drift/filter.md> for more details.

cmd/short_docs/drift/drift_overview.md

@@ -0,0 +1,28 @@
+# Introduction
+
+Tusk Drift enables you to record and replay traces from real traffic. These recorded traces make up
+an API test suite, which you can run locally or in CI/CD pipelines.
+
+## Concepts overview
+
+A **trace** represents the full path of an inbound request in your application.  
+
+A **span** represents a unit of work or operation in a trace. We capture all outbound requests made from your service (e.g., database calls, HTTP requests) in the path of a trace.
+
+Further reading: <https://opentelemetry.io/docs/concepts/signals/traces/>
+
+## Setup
+
+Setup involves creating a `.tusk/config.yaml` file in the directory of the service you wish to test.
+This lets Tusk know how to start your service and wait for it to be ready during replay mode.
+
+You can run `tusk drift setup` to start an AI agent to automatically set up your service for Tusk Drift or `tusk drift init` to start a configuration wizard.
+
+## Test workflow
+
+1. Instrument your app with the Tusk SDK.
+1. Once your app is up and ready, send traffic to it.
+    - Tusk will record traces in `.tusk/traces`.
+    - Shut down your app when you're done.
+1. Run `tusk drift run` to run these traces locally.
+1. Set up a workflow to run tests in your CI/CD pipeline.

cmd/short_docs/run.md → cmd/short_docs/drift/drift_run.md

@@ -42,7 +42,7 @@ An interactive session is started by default; use `-p`/`--print` for noninteract
 
 ### Cloud mode
 
-- `tusk run --cloud`: fetches all tests from Tusk Drift Cloud for your service and runs them locally; no Tusk Drift run is created and results are not uploaded.
-- `tusk run --cloud --ci`: creates a Tusk Drift run, fetches your test suite from Tusk Drift Cloud, and uploads test results. Use `-a/--all-cloud-trace-tests` to run all tests instead of the run-scoped suite.
-- `tusk run --cloud --ci --validate-suite-if-default-branch`: on the default branch, creates a validation run, fetches draft and in-suite tests, and validates they can be replayed before adding them to the suite. On other branches, this flag is ignored and the command behaves like `--cloud --ci`.
+- `tusk drift run --cloud`: fetches all tests from Tusk Drift Cloud for your service and runs them locally; no Tusk Drift run is created and results are not uploaded.
+- `tusk drift run --cloud --ci`: creates a Tusk Drift run, fetches your test suite from Tusk Drift Cloud, and uploads test results. Use `-a/--all-cloud-trace-tests` to run all tests instead of the run-scoped suite.
+- `tusk drift run --cloud --ci --validate-suite-if-default-branch`: on the default branch, creates a validation run, fetches draft and in-suite tests, and validates they can be replayed before adding them to the suite. On other branches, this flag is ignored and the command behaves like `--cloud --ci`.
 - `--trace-test-id` may be used with `--cloud` to run a single cloud trace test.

cmd/short_docs/overview.md

@@ -1,28 +1,15 @@
-# Introduction
+# Tusk CLI
 
-Tusk Drift enables you to record and replay traces from real traffic. These recorded traces make up
-an API test suite, which you can run locally or in CI/CD pipelines.
+The Tusk CLI provides tools for automated testing workflows across two products:
 
-## Concepts overview
+- **Tusk Drift** records real API traffic and replays it as deterministic API tests locally or in CI/CD.
+- **Tusk Unit** lets you inspect, review, and apply unit tests generated by Tusk.
 
-A **trace** represents the full path of an inbound request in your application.  
+## Common starting points
 
-A **span** represents a unit of work or operation in a trace. We capture all outbound requests made from your service (e.g., database calls, HTTP requests) in the path of a trace.
+- `tusk drift setup` to configure Tusk Drift for a service
+- `tusk drift run` to replay recorded traces
+- `tusk unit latest-run` to inspect the latest unit test generation run for your branch
+- `tusk auth login` to authenticate with Tusk Cloud
 
-Further reading: <https://opentelemetry.io/docs/concepts/signals/traces/>
-
-## Setup
-
-Setup involves creating a `.tusk/config.yaml` file in the directory of the service you wish to test.
-This lets Tusk know how to start your service and wait for it to ready during replay mode.
-
-You can run `tusk drift setup` to start an AI agent to automatically set up your service for Tusk Drift or `tusk drift init` to start a configuration wizard.
-
-## Test workflow
-
-1. Instrument your app with the Tusk SDK.
-1. Once your app is up and ready, send traffic to it.
-    - Tusk will record traces in `.tusk/traces`.
-    - Shut down your app when you're done.
-1. Run `tusk drift run` to run these traces locally.
-1. Set up a workflow to run tests in your CI/CD pipeline.
+Use `tusk <command> --help` for details on a specific workflow.

cmd/short_docs/unit/overview.md

@@ -0,0 +1,16 @@
+# Tusk Unit
+
+Tusk Unit lets you inspect and apply unit tests generated by Tusk for a pull request or branch.
+
+The data-returning `tusk unit` subcommands output JSON, which makes them work well in terminals, scripts, and agent workflows.
+
+## Typical workflow
+
+1. Check the latest run for the current repo and branch with `tusk unit latest-run`.
+2. Inspect the run and its generated scenarios with `tusk unit get-run <run-id>`.
+3. Review a specific scenario with `tusk unit get-scenario --run-id <run-id> --scenario-id <scenario-id>`.
+4. Apply generated diffs with `tusk unit get-diffs <run-id> | jq -r '.files[].diff' | git apply`.
+
+## Authentication
+
+Run `tusk auth login`, or set `TUSK_API_KEY` for non-interactive use.

cmd/unit.go

@@ -2,18 +2,23 @@ package cmd
 
 import (
 	"context"
+	_ "embed"
 	"encoding/json"
 	"fmt"
 	"os"
 
 	"github.com/Use-Tusk/tusk-cli/internal/api"
+	"github.com/Use-Tusk/tusk-cli/internal/utils"
 	"github.com/spf13/cobra"
 )
 
+//go:embed short_docs/unit/overview.md
+var unitOverviewContent string
+
 var unitCmd = &cobra.Command{
 	Use:          "unit",
 	Short:        "Commands for Tusk unit test workflows",
-	Long:         "Retrieve Tusk unit test generation runs and scenarios for local review and agent workflows.",
+	Long:         utils.RenderMarkdown(unitOverviewContent),
 	SilenceUsage: true,
 }