Merge pull request #37 from hashicorp/docs/style-updates-auto-gen

Update docs and auto gen so it is consistent with product docs

README.md

@@ -1,6 +1,6 @@
 # hcp
 
-`hcp` allows you to interact with the [HashiCorp Cloud
+`hcp` lets you interact with the [HashiCorp Cloud
 Platform](https://cloud.hashicorp.com) on the command line.
 
 ![hcp](assets/hcp.png?raw=true "screenshot of HCP CLI")

internal/commands/auth/auth.go

@@ -2,13 +2,16 @@ package auth
 
 import (
 	"github.com/hashicorp/hcp/internal/pkg/cmd"
+	"github.com/hashicorp/hcp/internal/pkg/heredoc"
 )
 
 func NewCmdAuth(ctx *cmd.Context) *cmd.Command {
 	cmd := &cmd.Command{
 		Name:      "auth",
 		ShortHelp: "Authenticate to HCP.",
-		LongHelp:  "Manage authentication to HCP.",
+		LongHelp: heredoc.New(ctx.IO).Must(`
+		The {{ template "mdCodeOrBold" "hcp auth" }} command group lets you manage authentication to HCP.
+		`),
 		Examples: []cmd.Example{
 			{
 				Preamble: "Login interactively using a browser:",

internal/commands/auth/login.go

@@ -31,7 +31,7 @@ func NewCmdLogin(ctx *cmd.Context) *cmd.Command {
 		Name:      "login",
 		ShortHelp: "Login to HCP.",
 		LongHelp: heredoc.New(ctx.IO).Must(`
-		Login is used to authenticate to HCP.
+		The {{ template "mdCodeOrBold" "hcp auth login" }} command lets you login to authenticate to HCP.
 
 		If no arguments are provided, authentication occurs for your user principal by initiating a web browser login flow.
 

internal/commands/auth/logout.go

@@ -18,7 +18,7 @@ func NewCmdLogout(ctx *cmd.Context) *cmd.Command {
 		Name:      "logout",
 		ShortHelp: "Logout from HCP.",
 		LongHelp: heredoc.New(ctx.IO).Must(`
-		Log out to remove access to HCP.
+		The {{ template "mdCodeOrBold" "hcp auth logout" }} command logs out to remove access to HCP.
 		`),
 		Examples: []cmd.Example{
 			{

internal/commands/auth/print_access_token.go

@@ -14,7 +14,8 @@ func NewCmdPrintAccessToken(ctx *cmd.Context) *cmd.Command {
 		Name:      "print-access-token",
 		ShortHelp: "Print the access token for the authenticated account.",
 		LongHelp: heredoc.New(ctx.IO).Must(`
-		Print an access token for the currently authenticated account.
+		The {{ template "mdCodeOrBold" "hcp auth print-access-token" }} command 
+		prints an access token for the currently authenticated account.
 
 		The output of this command can be used to set the {{ template "mdCodeOrBold"
 		"Authorization: Bearer <access_token>" }} HTTP header when manually making API requests.

internal/commands/hcp/hcp.go

@@ -15,7 +15,7 @@ func NewCmdHcp(ctx *cmd.Context) *cmd.Command {
 	c := &cmd.Command{
 		Name:      "hcp",
 		ShortHelp: "Interact with HCP.",
-		LongHelp:  "The HCP Command Line Interface is a unified tool to manage your HCP services.",
+		LongHelp:  "The HCP command-line interface (CLI) is a unified tool to manage your HCP services.",
 	}
 
 	//  _   _  ___ _____ _____

internal/commands/iam/groups/groups.go

@@ -11,7 +11,7 @@ func NewCmdGroups(ctx *cmd.Context) *cmd.Command {
 		Name:      "groups",
 		ShortHelp: "Manage HCP Groups.",
 		LongHelp: heredoc.New(ctx.IO).Must(`
-		The {{ template "mdCodeOrBold" "hcp iam groups" }} command group allows you to
+		The {{ template "mdCodeOrBold" "hcp iam groups" }} command group lets you
 		manage HCP groups as well as their memberships.
 
 		Groups help manage users and their access at scale. Each member of a

internal/commands/iam/groups/members/list.go

@@ -26,7 +26,7 @@ func NewCmdList(ctx *cmd.Context, runF func(*ListOpts) error) *cmd.Command {
 
 	cmd := &cmd.Command{
 		Name:      "list",
-		ShortHelp: "List the the members of a group.",
+		ShortHelp: "List the members of a group.",
 		LongHelp: heredoc.New(ctx.IO).Must(`
 		The {{ template "mdCodeOrBold" "hcp iam groups members list" }} command lists the members of a group.
 		`),

internal/commands/iam/groups/members/members.go

@@ -10,7 +10,7 @@ func NewCmdMembers(ctx *cmd.Context) *cmd.Command {
 		Name:      "members",
 		ShortHelp: "Manage group membership.",
 		LongHelp: heredoc.New(ctx.IO).Must(`
-		The {{ template "mdCodeOrBold" "hcp iam groups members" }} command group allows you to manage group membership.
+		The {{ template "mdCodeOrBold" "hcp iam groups members" }} command group lets you manage group membership.
 		`),
 	}
 

internal/commands/iam/iam.go

@@ -13,9 +13,9 @@ import (
 func NewCmdIam(ctx *cmd.Context) *cmd.Command {
 	cmd := &cmd.Command{
 		Name:      "iam",
-		ShortHelp: "Identity and access management.",
+		ShortHelp: "Manage identity and access management.",
 		LongHelp: heredoc.New(ctx.IO).Must(`
-		The {{ template "mdCodeOrBold" "hcp iam" }} command group allows you to manage HCP identities
+		The {{ template "mdCodeOrBold" "hcp iam" }} command group lets you manage HCP identities
 		including users, groups, and service principals.
 
 		Service principal keys or workload identity providers may also be managed. When accessing

internal/commands/iam/serviceprincipals/create.go

@@ -36,7 +36,9 @@ func NewCmdCreate(ctx *cmd.Context, runF func(*CreateOpts) error) *cmd.Command {
 		scope to limit access to the service principal and to locate the service
 		principal near the resources it will be accessing.
 
-		To create an organization service principal, set the --project flag to "-".
+		To create an organization service principal, set the 
+		{{ template "mdCodeOrBold" "--project" }}
+		flag to {{ template "mdCodeOrBold" "-" }}.
 		`),
 		Examples: []cmd.Example{
 			{

internal/commands/iam/serviceprincipals/keys/create.go

@@ -38,8 +38,9 @@ func NewCmdCreate(ctx *cmd.Context, runF func(*CreateOpts) error) *cmd.Command {
 		to leak into shell history. The HCP CLI allows authenticating via credential files using
 		{{ template "mdCodeOrBold" "hcp auth login --cred-file=PATH" }}. Prefer using credential files if your workflow allows it.
 
-		To create a key for an organization service principal, pass the service principal's resource name or set the --project
-		flag to "-" and pass its resource name suffix.
+		To create a key for an organization service principal, pass the service 
+		principal's resource name or set the {{ template "mdCodeOrBold" "--project" }}
+		flag to {{ template "mdCodeOrBold" "-" }} and pass its resource name suffix.
 		`),
 		Examples: []cmd.Example{
 			{

internal/commands/iam/serviceprincipals/keys/keys.go

@@ -10,7 +10,7 @@ func NewCmdKeys(ctx *cmd.Context) *cmd.Command {
 		Name:      "keys",
 		ShortHelp: "Create and manage service principals keys.",
 		LongHelp: heredoc.New(ctx.IO).Must(`
-		The {{ template "mdCodeOrBold" "hcp iam service-principals keys" }} command group is used to create
+		The {{ template "mdCodeOrBold" "hcp iam service-principals keys" }} command group lets you create
 		and manage service principals keys.
 
 		A service principal key is the credential used by a service principal to authenticate with HCP

internal/commands/iam/serviceprincipals/keys/list.go

@@ -26,8 +26,9 @@ func NewCmdList(ctx *cmd.Context, runF func(*ListOpts) error) *cmd.Command {
 		LongHelp: heredoc.New(ctx.IO).Must(`
 		The {{ template "mdCodeOrBold" "hcp iam service-principals keys list" }} command lists a service principal's keys.
 
-		To list keys for an organization service principal, pass the service principal's resource name or set the --project
-		flag to "-" and pass its resource name suffix.
+		To list keys for an organization service principal, pass the service 
+		principal's resource name or set the {{ template "mdCodeOrBold" "--project" }}
+		flag to {{ template "mdCodeOrBold" "-" }} and pass its resource name suffix.
 		`),
 		Examples: []cmd.Example{
 			{

internal/commands/iam/serviceprincipals/list.go

@@ -27,7 +27,8 @@ func NewCmdList(ctx *cmd.Context, runF func(*ListOpts) error) *cmd.Command {
 		LongHelp: heredoc.New(ctx.IO).Must(`
 		The {{ template "mdCodeOrBold" "hcp iam service-principals list" }} command lists the service principals.
 
-		To list organization service principals, set the --project flag to "-".
+		To list organization service principals, set the 
+		{{ template "mdCodeOrBold" "--project" }} flag to {{ template "mdCodeOrBold" "-" }}.
 		`),
 		RunF: func(c *cmd.Command, args []string) error {
 			if runF != nil {

internal/commands/iam/serviceprincipals/read.go

@@ -27,8 +27,9 @@ func NewCmdRead(ctx *cmd.Context, runF func(*ReadOpts) error) *cmd.Command {
 		The {{ template "mdCodeOrBold" "hcp iam service-principals read" }} command reads details about the given
 		service principal.
 
-		To read an organization service principal, pass the service principal's resource name or set the --project
-		flag to "-" and pass its resource name suffix.
+		To read an organization service principal, pass the service principal's 
+		resource name or set the {{ template "mdCodeOrBold" "--project" }}
+		flag to {{ template "mdCodeOrBold" "-" }} and pass its resource name suffix.
 		`),
 		Examples: []cmd.Example{
 			{

internal/commands/iam/serviceprincipals/sps.go

@@ -12,14 +12,15 @@ func NewCmdServicePrincipals(ctx *cmd.Context) *cmd.Command {
 		Aliases:   []string{"sp"},
 		ShortHelp: "Create and manage service principals.",
 		LongHelp: heredoc.New(ctx.IO).Must(`
-		The {{ template "mdCodeOrBold" "hcp iam service-principals" }} command group is used to create
+		The {{ template "mdCodeOrBold" "hcp iam service-principals" }} command group lets you create
 		and manage service principals.
 
 		A service principals is a principal that is typically used by an application or workload that
 		interacts with HCP. Your application uses the service principal to authenticate to HCP so that
 		users aren't directly involved.
 
-		Because service principals are principals, you can grant it permissions by granting a role. See the examples for guidance.
+		Because service principals are principals, you can grant it permissions
+		by granting a role. Refer to the examples for guidance.
 		`),
 		Examples: []cmd.Example{
 			{

internal/commands/iam/users/users.go

@@ -10,7 +10,7 @@ func NewCmdUsers(ctx *cmd.Context) *cmd.Command {
 		Name:      "users",
 		ShortHelp: "Manage an organization's users.",
 		LongHelp: heredoc.New(ctx.IO).Must(`
-		The {{ template "mdCodeOrBold" "hcp iam users" }} command group allows you to manage
+		The {{ template "mdCodeOrBold" "hcp iam users" }} command group lets you manage
 		the users of an HCP organization.
 		`),
 	}

internal/commands/iam/workloadidentityproviders/create_aws.go

@@ -40,10 +40,10 @@ func NewCmdCreateAWS(ctx *cmd.Context, runF func(*CreateAWSOpts) error) *cmd.Com
 		string that is evaluated when exchanging tokens. It has access to the following variables:
 
 		{{ PreserveNewLines }}
-		  * "aws.arn": The AWS ARN associated with the calling entity.
-		  * "aws.account_id": The AWS account ID number of the account that owns
+			* {{ template "mdCodeOrBold" "aws.arn" }}: The AWS ARN associated with the calling entity.
+			* {{ template "mdCodeOrBold" "aws.account_id" }}: The AWS account ID number of the account that owns
 		    or contains the calling entity.
-		  * "aws.user_id": The unique identifier of the calling entity.
+			* {{ template "mdCodeOrBold" "aws.user_id" }}: The unique identifier of the calling entity.
 		{{ PreserveNewLines }}
 
 		An example conditional access statement that restricts access to a specific role is,
@@ -101,13 +101,13 @@ func NewCmdCreateAWS(ctx *cmd.Context, runF func(*CreateAWSOpts) error) *cmd.Com
 					The conditional_access statement can access the following variables:
 
 					{{ PreserveNewLines }}
-					  * "aws.arn": The AWS ARN associated with the calling entity.
-					  * "aws.account_id": The AWS account ID number of the account that owns
+					  * {{ template "mdCodeOrBold" "aws.arn" }}: The AWS ARN associated with the calling entity.
+					  * {{ template "mdCodeOrBold" "aws.account_id" }}: The AWS account ID number of the account that owns
 					    or contains the calling entity.
-					  * "aws.user_id": The unique identifier of the calling entity.
+					  * {{ template "mdCodeOrBold" "aws.user_id" }}: The unique identifier of the calling entity.
 					{{ PreserveNewLines }}
 
-					For details on the values of each variable, see the
+					For details on the values of each variable, refer to the
 					{{ Link "AWS documentation" "https://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html#API_GetCallerIdentity_ResponseElements" }}.
 					`),
 					Value:    flagvalue.Simple("", &opts.ConditionalAccess),

internal/commands/iam/workloadidentityproviders/create_cred_file.go

@@ -124,7 +124,11 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error
 				  --source-file=/var/run/secrets/tokens/hcp_token \
 				  --source-json-pointer=/access_token \
 				  --output-file=credentials.json
-
+				`),
+			},
+			{
+				Preamble: `Create a credential file that sources the token from a file:`,
+				Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(`
 				# Assuming the file only contains the access token:
 				$ hcp iam workload-identity-providers create-cred-file \
 				  iam/project/123/service-principal/my-sp/workload-identity-provider/k8s \
@@ -145,13 +149,21 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error
 				  --source-url="https://example-oidc-provider.com/token" \
 				  --source-json-pointer=/access_token \
 				  --output-file=credentials.json
-
-				# Assuming the response only contains the access token:
+				`),
+			},
+			{
+				Preamble: `Create a credential file that sources the token from an URL:`,
+				Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(`
+				# Assuming the file only contains the access token:
 				$ hcp iam workload-identity-providers create-cred-file \
 				  iam/project/123/service-principal/my-sp/workload-identity-provider/example \
 				  --source-url=https://example-oidc-provider.com/token \
 				  --output-file=credentials.json
-
+				`),
+			},
+			{
+				Preamble: `Create a credential file that sources the token from an URL:`,
+				Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(`
 				# To add headers to the request, use the --source-header flag:
 				$ hcp iam workload-identity-providers create-cred-file \
 				  iam/project/123/service-principal/my-sp/workload-identity-provider/example \
@@ -174,7 +186,11 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error
 				  --source-env=ACCESS_TOKEN \
 				  --source-json-pointer=/access_token \
 				  --output-file=credentials.json
-
+				`),
+			},
+			{
+				Preamble: `Create a credential file that sources the token from an environment variable:`,
+				Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(`
 				# Assuming the environment variable only contains the access token:
 				$ hcp iam workload-identity-providers create-cred-file \
 				  iam/project/123/service-principal/my-sp/workload-identity-provider/example \
@@ -231,7 +247,7 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error
 					{{ PreserveNewLines }}
 					  * The Client ID of the User Assigned Managed Identity (UUID)
 					  * The Application ID URI of the Microsoft Entra ID Application
-					    (api://123-456-678-901).
+					    ({{ template "mdCodeOrBold" "api://123-456-678-901" }}).
 					{{ PreserveNewLines }}
 
 					For more details on the resource parameter, see the
@@ -256,8 +272,8 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error
 					Set if exchanging an GCP workload identity.
 
 					It is assumed the workload identity provider was created
-					with the issuer URI set to "https://accounts.google.com" and
-					the default allowed audiences.
+					with the issuer URI set to {{ template "mdCodeOrBold" "https://accounts.google.com" }}
+					and the default allowed audiences.
 					`),
 					Value:         flagvalue.Simple(false, &opts.GCP),
 					IsBooleanFlag: true,
@@ -285,12 +301,13 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error
 					DisplayValue: "/PATH/TO/CREDENTIAL",
 					Description: heredoc.New(ctx.IO).Must(`
 A JSON pointer that indicates how to access the credential from a JSON.
-If used with the "source-url" flag, the pointer is used to extract the
-credential from the JSON response from calling the URL. If used with the
-"source-file" flag, the pointer is used to extract the credential read from
-the JSON file. Similarly, if used with the "source-env" flag, the pointer
-is used to extract the credential from the environment variable whose value
-is a JSON object.
+If used with the {{ template "mdCodeOrBold" "source-url" }} flag, the pointer
+is used to extract the credential from the JSON response from calling the URL.
+If used with the {{ template "mdCodeOrBold" "source-file" }} flag, the pointer
+is used to extract the credential read from the JSON file. Similarly, if used
+with the {{ template "mdCodeOrBold" "source-env" }} flag, the pointer is used to
+extract the credential from the environment variable whose value is a JSON
+object.
 
 As an example, if the JSON payload containing the credential file is:
 
@@ -300,10 +317,11 @@ As an example, if the JSON payload containing the credential file is:
     "access_token": "nested-credentials"
   }
 } {{- end }}
-{{- CodeBlock "credentials" "json" }}
+{{- CodeBlock "credentials" "json hideClipboard" }}
 
-The top level access token can be accessed using the pointer "/access_token" and the
-nested access token can be accessed using the pointer "/nested/access_token".
+You can access the top level access token using the pointer
+{{ template "mdCodeOrBold" "/access_token" }} and the nested access token can be
+accessed using the pointer {{ template "mdCodeOrBold" "/nested/access_token" }}.
 					`),
 					Value: flagvalue.Simple("", &opts.CredentialJSONPointer),
 				},

internal/commands/iam/workloadidentityproviders/create_oidc.go

@@ -63,9 +63,12 @@ func NewCmdCreateOIDC(ctx *cmd.Context, runF func(*CreateOIDCOpts) error) *cmd.C
 				`),
 			},
 			{
-				Preamble: `GCP - Allow exchanging a Service Account Identity:`,
+				Preamble: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(`
+					GCP - Allow exchanging a Service Account Identity
+
+					{{ Link "Full List of claims" "https://cloud.google.com/compute/docs/instances/verifying-instance-identity#payload" }}:
+				`),
 				Command: heredoc.New(ctx.IO, heredoc.WithNoWrap(), heredoc.WithPreserveNewlines()).Must(`
-				# List of claims: https://cloud.google.com/compute/docs/instances/verifying-instance-identity#payload
 				$ hcp iam workload-identity-providers create-oidc gcp-example-service-account \
 				  --service-principal=iam/project/PROJECT/service-principal/example-sp \
 				  --issuer=https://accounts.google.com \
@@ -74,9 +77,12 @@ func NewCmdCreateOIDC(ctx *cmd.Context, runF func(*CreateOIDCOpts) error) *cmd.C
 				`),
 			},
 			{
-				Preamble: `GitLab - Allow exchanging a GitLab:`,
+				Preamble: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(`
+					GitLab - Allow exchanging a GitLab
+
+					{{ Link "Full list of claims" "https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html#token-payload" }}:
+				`),
 				Command: heredoc.New(ctx.IO, heredoc.WithNoWrap(), heredoc.WithPreserveNewlines()).Must(`
-				# Full list of claims: https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html#token-payload
 				$ hcp iam workload-identity-providers create-oidc gcp-example-service-account \
 				  --service-principal=iam/project/PROJECT/service-principal/example-sp \
 				  --issuer=https://gitlab.com \
@@ -117,7 +123,7 @@ func NewCmdCreateOIDC(ctx *cmd.Context, runF func(*CreateOIDCOpts) error) *cmd.C
 					The access token must have an audience that is contained in this set.
 
 					If no audience is set, the default allowed audience will be the resource name of the provider. The format will be:
-					{{ Italic "iam/project/PROJECT_ID/service-principal/SP_NAME/workload-identity-provider/WIP_NAME" }}.
+					{{ template "mdCodeOrBold" "iam/project/PROJECT_ID/service-principal/SP_NAME/workload-identity-provider/WIP_NAME" }}.
 					`),
 					Value:      flagvalue.SimpleSlice(nil, &opts.AllowedAudiences),
 					Repeatable: true,
@@ -131,7 +137,9 @@ func NewCmdCreateOIDC(ctx *cmd.Context, runF func(*CreateOIDCOpts) error) *cmd.C
 					the service principal.
 
 					The conditional_access statement can access any claim from the external identity token using
-					the "jwt_claims.<claim_name>" syntax. As an example, access the subject claim with "jwt_claims.sub".
+					the {{ template "mdCodeOrBold" "jwt_claims.<claim_name>" }} syntax.
+					As an example, access the subject claim with
+					{{ template "mdCodeOrBold" "jwt_claims.sub" }}.
 					`),
 					Value:    flagvalue.Simple("", &opts.ConditionalAccess),
 					Required: true,

internal/commands/iam/workloadidentityproviders/list.go

@@ -49,7 +49,7 @@ func NewCmdList(ctx *cmd.Context, runF func(*ListOpts) error) *cmd.Command {
 			Args: []cmd.PositionalArgument{
 				{
 					Name:          "SP_NAME",
-					Documentation: heredoc.New(ctx.IO).Mustf(helper.SPNameArgDoc, "list workload identity providers for."),
+					Documentation: heredoc.New(ctx.IO).Mustf(helper.SPNameArgDoc, "list workload identity providers for"),
 				},
 			},
 		},