feat(api): docs

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 19
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/stainless%2Fstainless-v0-e588492ce099ac1af79467a22ecac606b1fe8cf78a82fd37137bf8e30ac1a80e.yml
-openapi_spec_hash: 7311d0d71ab64604d2b298e3c38b945f
-config_hash: b4d273d7503424c98b7d284102d23fb1
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/stainless%2Fstainless-v0-a015455f60c6b613608a0a1fc4918a41593038160a16b09f714f601ab98c84bf.yml
+openapi_spec_hash: 6f4ebb173c63d77efa9addde9b11f69e
+config_hash: 50a257a9f90f8a010873c283e2832095

README.md

@@ -45,8 +45,8 @@ stl [resource] [command] [flags]
 
 ```sh
 stl builds create \
-  --project project \
-  --revision string
+  --project stainless \
+  --revision main
 ```
 
 For details about specific commands, use the `--help` flag.

pkg/cmd/build.go

@@ -225,7 +225,7 @@ func waitForBuildCompletion(ctx context.Context, client stainless.Client, build
 
 var buildsCreate = cli.Command{
 	Name:  "create",
-	Usage: "Create a new build",
+	Usage: "Create a build, on top of a project branch, against a given input revision.",
 	Flags: []cli.Flag{
 		&jsonflag.JSONStringFlag{
 			Name: "project",
@@ -310,7 +310,7 @@ var buildsCreate = cli.Command{
 
 var buildsRetrieve = cli.Command{
 	Name:  "retrieve",
-	Usage: "Retrieve a build by ID",
+	Usage: "Retrieve a build by its ID.",
 	Flags: []cli.Flag{
 		&cli.StringFlag{
 			Name: "build-id",
@@ -322,7 +322,7 @@ var buildsRetrieve = cli.Command{
 
 var buildsList = cli.Command{
 	Name:  "list",
-	Usage: "List builds for a project",
+	Usage: "List user-triggered builds for a given project.",
 	Flags: []cli.Flag{
 		&jsonflag.JSONStringFlag{
 			Name: "project",
@@ -366,7 +366,7 @@ var buildsList = cli.Command{
 
 var buildsCompare = cli.Command{
 	Name:  "compare",
-	Usage: "Creates two builds whose outputs can be compared directly",
+	Usage: "Create two builds whose outputs can be directly compared with each other.",
 	Flags: []cli.Flag{
 		&jsonflag.JSONStringFlag{
 			Name: "base.branch",

pkg/cmd/builddiagnostic.go

@@ -13,7 +13,7 @@ import (
 
 var buildsDiagnosticsList = cli.Command{
 	Name:  "list",
-	Usage: "Get diagnostics for a build",
+	Usage: "Get the list of diagnostics for a given build.",
 	Flags: []cli.Flag{
 		&cli.StringFlag{
 			Name: "build-id",

pkg/cmd/buildtargetoutput.go

@@ -14,7 +14,7 @@ import (
 
 var buildsTargetOutputsRetrieve = cli.Command{
 	Name:  "retrieve",
-	Usage: "Download the output of a build target",
+	Usage: "Retrieve a method to download an output for a given build target.",
 	Flags: []cli.Flag{
 		&cli.BoolFlag{
 			Name: "pull",

pkg/cmd/org.go

@@ -11,7 +11,7 @@ import (
 
 var orgsRetrieve = cli.Command{
 	Name:  "retrieve",
-	Usage: "Retrieve an organization by name",
+	Usage: "Retrieve an organization by name.",
 	Flags: []cli.Flag{
 		&cli.StringFlag{
 			Name: "org",
@@ -23,7 +23,7 @@ var orgsRetrieve = cli.Command{
 
 var orgsList = cli.Command{
 	Name:            "list",
-	Usage:           "List organizations the user has access to",
+	Usage:           "List organizations accessible to the current authentication method.",
 	Flags:           []cli.Flag{},
 	Action:          handleOrgsList,
 	HideHelpCommand: true,

pkg/cmd/project.go

@@ -13,7 +13,7 @@ import (
 
 var projectsCreate = cli.Command{
 	Name:  "create",
-	Usage: "Create a new project",
+	Usage: "Create a new project.",
 	Flags: []cli.Flag{
 		&jsonflag.JSONStringFlag{
 			Name: "display-name",
@@ -57,7 +57,7 @@ var projectsCreate = cli.Command{
 
 var projectsRetrieve = cli.Command{
 	Name:  "retrieve",
-	Usage: "Retrieve a project by name",
+	Usage: "Retrieve a project by name.",
 	Flags: []cli.Flag{
 		&cli.StringFlag{
 			Name: "project",
@@ -69,7 +69,7 @@ var projectsRetrieve = cli.Command{
 
 var projectsUpdate = cli.Command{
 	Name:  "update",
-	Usage: "Update a project's properties",
+	Usage: "Update a project's properties.",
 	Flags: []cli.Flag{
 		&cli.StringFlag{
 			Name: "project",
@@ -88,7 +88,7 @@ var projectsUpdate = cli.Command{
 
 var projectsList = cli.Command{
 	Name:  "list",
-	Usage: "List projects in an organization, from oldest to newest",
+	Usage: "List projects in an organization, from oldest to newest.",
 	Flags: []cli.Flag{
 		&jsonflag.JSONStringFlag{
 			Name: "cursor",

pkg/cmd/projectbranch.go

@@ -13,7 +13,7 @@ import (
 
 var projectsBranchesCreate = cli.Command{
 	Name:  "create",
-	Usage: "Create a new branch for a project",
+	Usage: "Create a new branch for a project.",
 	Flags: []cli.Flag{
 		&cli.StringFlag{
 			Name: "project",
@@ -47,7 +47,7 @@ var projectsBranchesCreate = cli.Command{
 
 var projectsBranchesRetrieve = cli.Command{
 	Name:  "retrieve",
-	Usage: "Retrieve a project branch",
+	Usage: "Retrieve a project branch by name.",
 	Flags: []cli.Flag{
 		&cli.StringFlag{
 			Name: "project",
@@ -62,7 +62,7 @@ var projectsBranchesRetrieve = cli.Command{
 
 var projectsBranchesList = cli.Command{
 	Name:  "list",
-	Usage: "List project branches",
+	Usage: "Retrieve a project branch by name.",
 	Flags: []cli.Flag{
 		&cli.StringFlag{
 			Name: "project",
@@ -88,7 +88,7 @@ var projectsBranchesList = cli.Command{
 
 var projectsBranchesDelete = cli.Command{
 	Name:  "delete",
-	Usage: "Delete a project branch",
+	Usage: "Delete a project branch by name.",
 	Flags: []cli.Flag{
 		&cli.StringFlag{
 			Name: "project",
@@ -103,7 +103,7 @@ var projectsBranchesDelete = cli.Command{
 
 var projectsBranchesRebase = cli.Command{
 	Name:  "rebase",
-	Usage: "Rebase a project branch",
+	Usage: "Rebase a project branch.",
 	Flags: []cli.Flag{
 		&cli.StringFlag{
 			Name: "project",

pkg/cmd/projectconfig.go

@@ -13,7 +13,7 @@ import (
 
 var projectsConfigsRetrieve = cli.Command{
 	Name:  "retrieve",
-	Usage: "Retrieve configuration files for a project",
+	Usage: "Retrieve the configuration files for a given project.",
 	Flags: []cli.Flag{
 		&cli.StringFlag{
 			Name: "project",
@@ -39,7 +39,7 @@ var projectsConfigsRetrieve = cli.Command{
 
 var projectsConfigsGuess = cli.Command{
 	Name:  "guess",
-	Usage: "Generate configuration suggestions based on an OpenAPI spec",
+	Usage: "Generate suggestions for changes to config files based on an OpenAPI spec.",
 	Flags: []cli.Flag{
 		&cli.StringFlag{
 			Name: "project",