From dd3847eb7721d0301397f81f70aa3d423122ca1e Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Mon, 18 Mar 2024 23:07:52 -0700 Subject: [PATCH 1/8] update auto gen so its more consistent with other cli docs, update consistent descriptions --- internal/commands/auth/auth.go | 2 +- internal/commands/auth/login.go | 2 +- internal/commands/hcp/hcp.go | 2 +- .../iam/serviceprincipals/keys/keys.go | 2 +- .../commands/iam/serviceprincipals/sps.go | 2 +- .../workloadidentityproviders/create_aws.go | 2 +- .../organizations/iam/delete_binding.go | 2 +- .../commands/organizations/iam/read_policy.go | 2 +- .../commands/organizations/iam/set_policy.go | 2 +- internal/commands/organizations/list.go | 2 +- internal/commands/organizations/read.go | 2 +- internal/commands/profile/display.go | 2 +- internal/commands/profile/get.go | 2 +- internal/commands/profile/init.go | 2 +- .../commands/profile/profiles/activate.go | 2 +- internal/commands/profile/profiles/create.go | 2 +- internal/commands/profile/profiles/delete.go | 2 +- internal/commands/profile/profiles/list.go | 2 +- .../commands/profile/profiles/profiles.go | 7 +++-- internal/commands/profile/profiles/rename.go | 2 +- internal/commands/profile/set.go | 2 +- internal/commands/profile/unset.go | 2 +- internal/commands/projects/create.go | 2 +- internal/commands/projects/delete.go | 2 +- internal/commands/projects/list.go | 2 +- internal/commands/projects/read.go | 2 +- internal/commands/projects/update.go | 2 +- internal/commands/version/version.go | 2 +- .../waypoint/actionconfig/action_config.go | 3 +- .../commands/waypoint/actionconfig/create.go | 2 +- .../commands/waypoint/actionconfig/delete.go | 2 +- .../commands/waypoint/actionconfig/list.go | 2 +- .../commands/waypoint/actionconfig/read.go | 2 +- .../commands/waypoint/actionconfig/update.go | 2 +- internal/commands/waypoint/agent/group.go | 2 +- .../commands/waypoint/agent/group_delete.go | 2 +- .../commands/waypoint/agent/group_list.go | 2 +- internal/commands/waypoint/agent/run.go | 2 +- .../commands/waypoint/tfcconfig/tfc_config.go | 3 +- .../waypoint/tfcconfig/tfc_config_create.go | 2 +- internal/pkg/cmd/gen_md.go | 31 +++++++++---------- internal/pkg/cmd/gen_nav_json.go | 2 +- 42 files changed, 60 insertions(+), 60 deletions(-) diff --git a/internal/commands/auth/auth.go b/internal/commands/auth/auth.go index 3468df0a..0ed45532 100644 --- a/internal/commands/auth/auth.go +++ b/internal/commands/auth/auth.go @@ -8,7 +8,7 @@ func NewCmdAuth(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "auth", ShortHelp: "Authenticate to HCP.", - LongHelp: "Manage authentication to HCP.", + LongHelp: "The `hcp auth` command group lets you manage authentication to HCP.", Examples: []cmd.Example{ { Preamble: "Login interactively using a browser:", diff --git a/internal/commands/auth/login.go b/internal/commands/auth/login.go index 830e24b2..75f983a6 100644 --- a/internal/commands/auth/login.go +++ b/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. diff --git a/internal/commands/hcp/hcp.go b/internal/commands/hcp/hcp.go index 2a217024..90b4ef5b 100644 --- a/internal/commands/hcp/hcp.go +++ b/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.", } // Add the subcommands diff --git a/internal/commands/iam/serviceprincipals/keys/keys.go b/internal/commands/iam/serviceprincipals/keys/keys.go index 6088933e..3540968f 100644 --- a/internal/commands/iam/serviceprincipals/keys/keys.go +++ b/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 diff --git a/internal/commands/iam/serviceprincipals/sps.go b/internal/commands/iam/serviceprincipals/sps.go index a0f3da44..903f0281 100644 --- a/internal/commands/iam/serviceprincipals/sps.go +++ b/internal/commands/iam/serviceprincipals/sps.go @@ -19,7 +19,7 @@ func NewCmdServicePrincipals(ctx *cmd.Context) *cmd.Command { 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{ { diff --git a/internal/commands/iam/workloadidentityproviders/create_aws.go b/internal/commands/iam/workloadidentityproviders/create_aws.go index 1eae0453..7e60d699 100644 --- a/internal/commands/iam/workloadidentityproviders/create_aws.go +++ b/internal/commands/iam/workloadidentityproviders/create_aws.go @@ -107,7 +107,7 @@ func NewCmdCreateAWS(ctx *cmd.Context, runF func(*CreateAWSOpts) error) *cmd.Com * "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), diff --git a/internal/commands/organizations/iam/delete_binding.go b/internal/commands/organizations/iam/delete_binding.go index 0076243d..00b1f3cd 100644 --- a/internal/commands/organizations/iam/delete_binding.go +++ b/internal/commands/organizations/iam/delete_binding.go @@ -23,7 +23,7 @@ func NewCmdDeleteBinding(ctx *cmd.Context, runF func(*DeleteBindingOpts) error) Name: "delete-binding", ShortHelp: "Delete an IAM policy binding for the organization.", LongHelp: heredoc.New(ctx.IO).Must(` - Deletes an IAM policy binding for the organization. A binding consists of a + The {{ template "mdCodeOrBold" "hcp organizations iam delete-binding" }} command deletes an IAM policy binding for the organization. A binding consists of a principal and a role. To view the existing role bindings, run {{ template "mdCodeOrBold" "hcp organizations iam read-policy" }}. diff --git a/internal/commands/organizations/iam/read_policy.go b/internal/commands/organizations/iam/read_policy.go index c109e31f..ac79add7 100644 --- a/internal/commands/organizations/iam/read_policy.go +++ b/internal/commands/organizations/iam/read_policy.go @@ -25,7 +25,7 @@ func NewCmdReadPolicy(ctx *cmd.Context, runF func(*ReadPolicyOpts) error) *cmd.C cmd := &cmd.Command{ Name: "read-policy", ShortHelp: "Read the IAM policy for the organization.", - LongHelp: "Read the IAM policy for the organization.", + LongHelp: "The `hcp organizations iam read-policy` command reads the IAM policy for the organization.", Examples: []cmd.Example{ { Preamble: "Read the IAM Policy for the organization:", diff --git a/internal/commands/organizations/iam/set_policy.go b/internal/commands/organizations/iam/set_policy.go index ade58415..cf181c62 100644 --- a/internal/commands/organizations/iam/set_policy.go +++ b/internal/commands/organizations/iam/set_policy.go @@ -30,7 +30,7 @@ func NewCmdSetPolicy(ctx *cmd.Context, runF func(*SetPolicyOpts) error) *cmd.Com Name: "set-policy", ShortHelp: "Set the IAM policy for the organization.", LongHelp: heredoc.New(ctx.IO).Must(` -Sets the IAM policy for the organization. Setting the entire policy must be done + The {{ template "mdCodeOrBold" "hcp organizations iam set-policy" }} command sets the IAM policy for the organization. Setting the entire policy must be done with great care. If adding or removing a single principal from the policy, prefer using {{ template "mdCodeOrBold" "hcp organizations iam add-binding" }} and the related {{ template "mdCodeOrBold" "hcp organizations iam delete-binding" }}. diff --git a/internal/commands/organizations/list.go b/internal/commands/organizations/list.go index 6aba2f3b..7fefbea2 100644 --- a/internal/commands/organizations/list.go +++ b/internal/commands/organizations/list.go @@ -24,7 +24,7 @@ func NewCmdList(ctx *cmd.Context, runF func(*ListOpts) error) *cmd.Command { cmd := &cmd.Command{ Name: "list", ShortHelp: "List organizations.", - LongHelp: "List the organizations the authenticated principal is a member of.", + LongHelp: "The `hcp organizations list` command lists the organizations the authenticated principal is a member of.", RunF: func(c *cmd.Command, args []string) error { if runF != nil { return runF(opts) diff --git a/internal/commands/organizations/read.go b/internal/commands/organizations/read.go index 5293d8b4..e15b3636 100644 --- a/internal/commands/organizations/read.go +++ b/internal/commands/organizations/read.go @@ -23,7 +23,7 @@ func NewCmdRead(ctx *cmd.Context, runF func(*ReadOpts) error) *cmd.Command { cmd := &cmd.Command{ Name: "read", ShortHelp: "Show metadata for the organization.", - LongHelp: "Show metadata for the organization.", + LongHelp: "The `hcp organizations read` command shows metadata for the organization.", Args: cmd.PositionalArguments{ Args: []cmd.PositionalArgument{ { diff --git a/internal/commands/profile/display.go b/internal/commands/profile/display.go index 55f720f0..368910c4 100644 --- a/internal/commands/profile/display.go +++ b/internal/commands/profile/display.go @@ -16,7 +16,7 @@ func NewCmdDisplay(ctx *cmd.Context) *cmd.Command { Name: "display", ShortHelp: "Display the active profile.", LongHelp: heredoc.New(ctx.IO).Mustf(` - {{ template "mdCodeOrBold" "hcp profile display" }} displays the active profile. + The {{ template "mdCodeOrBold" "hcp profile display" }} command displays the active profile. `), RunF: func(c *cmd.Command, args []string) error { return displayRun(&DisplayOpts{ diff --git a/internal/commands/profile/get.go b/internal/commands/profile/get.go index 31c5d2db..6de723c5 100644 --- a/internal/commands/profile/get.go +++ b/internal/commands/profile/get.go @@ -24,7 +24,7 @@ func NewCmdGet(ctx *cmd.Context) *cmd.Command { Name: "get", ShortHelp: "Get a HCP CLI Property.", LongHelp: heredoc.New(ctx.IO).Mustf(` - {{ template "mdCodeOrBold" "hcp profile get" }} gets the specified property in your active profile. + The {{ template "mdCodeOrBold" "hcp profile get" }} command gets the specified property in your active profile. To view all currently set properties, run {{ template "mdCodeOrBold" "hcp profile display" }}. `), diff --git a/internal/commands/profile/init.go b/internal/commands/profile/init.go index a7f61743..1f62599f 100644 --- a/internal/commands/profile/init.go +++ b/internal/commands/profile/init.go @@ -32,7 +32,7 @@ func NewCmdInit(ctx *cmd.Context) *cmd.Command { Name: "init", ShortHelp: "Initialize the current profile.", LongHelp: heredoc.New(ctx.IO).Mustf(` - init configures the HCP CLI to run commands against the correct context; namely against the + The {{ template "mdCodeOrBold" "hcp profile init" }} command configures the HCP CLI to run commands against the correct context; namely against the desired organization and project ID. This command is interactive. To set configuration using non-interactively prefer using {{ template "mdCodeOrBold" "hcp profile set" }}. diff --git a/internal/commands/profile/profiles/activate.go b/internal/commands/profile/profiles/activate.go index 43ab7cd6..7bd917b4 100644 --- a/internal/commands/profile/profiles/activate.go +++ b/internal/commands/profile/profiles/activate.go @@ -16,7 +16,7 @@ func NewCmdActivate(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "activate", ShortHelp: "Activates an existing profile.", - LongHelp: "Activates an existing profile.", + LongHelp: "The `hcp profile profiles activate` command activates an existing profile.", Examples: []cmd.Example{ { Preamble: "To active profile my-profile, run:", diff --git a/internal/commands/profile/profiles/create.go b/internal/commands/profile/profiles/create.go index 245ec5cf..bf0a8cf3 100644 --- a/internal/commands/profile/profiles/create.go +++ b/internal/commands/profile/profiles/create.go @@ -18,7 +18,7 @@ func NewCmdCreate(ctx *cmd.Context) *cmd.Command { Name: "create", ShortHelp: "Create a new HCP profile.", LongHelp: heredoc.New(ctx.IO).Mustf(` - Creates a new named profile. + The {{ template "mdCodeOrBold" "hcp profile profiles create" }} command creates a new named profile. Profile names start with a letter and may contain lower case letters a-z, upper case letters A-Z, digits 0-9, and hyphens '-'. The maximum length for diff --git a/internal/commands/profile/profiles/delete.go b/internal/commands/profile/profiles/delete.go index 32255a69..b56c8afa 100644 --- a/internal/commands/profile/profiles/delete.go +++ b/internal/commands/profile/profiles/delete.go @@ -17,7 +17,7 @@ func NewCmdDelete(ctx *cmd.Context) *cmd.Command { Name: "delete", ShortHelp: "Delete an existing HCP profile.", LongHelp: heredoc.New(ctx.IO).Must(` - Deletes an existing HCP profiles. If the profile is the active profile, it may not be deleted. + The {{ template "mdCodeOrBold" "hcp profile profiles delete" }} command deletes an existing HCP profiles. If the profile is the active profile, it may not be deleted. To delete the current active profile, first run {{ template "mdCodeOrBold" "hcp profile profiles activate" }} to active a different profile. diff --git a/internal/commands/profile/profiles/list.go b/internal/commands/profile/profiles/list.go index 0c367adc..bd459925 100644 --- a/internal/commands/profile/profiles/list.go +++ b/internal/commands/profile/profiles/list.go @@ -19,7 +19,7 @@ func NewCmdList(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "list", ShortHelp: "List existing HCP profiles.", - LongHelp: "List existing HCP profiles.", + LongHelp: "The `hcp profile profiles list` command lists existing HCP profiles.", Examples: []cmd.Example{ { Preamble: "To list existing profiles, run:", diff --git a/internal/commands/profile/profiles/profiles.go b/internal/commands/profile/profiles/profiles.go index c9376f6c..0269f5d8 100644 --- a/internal/commands/profile/profiles/profiles.go +++ b/internal/commands/profile/profiles/profiles.go @@ -18,9 +18,10 @@ func NewCmdProfiles(ctx *cmd.Context) *cmd.Command { Name: "profiles", ShortHelp: "Manage HCP profiles.", LongHelp: heredoc.New(ctx.IO).Must(` - Manage the set of named HCP profiles. New profiles can be created using - {{ template "mdCodeOrBold" "hcp profile profiles create" }} and existing - profiles can be activated using {{ template "mdCodeOrBold" "hcp profile profiles activate" }}. + The {{ template "mdCodeOrBold" "hcp profile profiles" }} command group lets you + manage the set of named HCP profiles. You can create new profiles using + {{ template "mdCodeOrBold" "hcp profile profiles create" }} and activate existing + profiles using {{ template "mdCodeOrBold" "hcp profile profiles activate" }}. To run a single command against a profile other than the active profile, run the command with the flag {{ template "mdCodeOrBold" "--profile" }}. `), diff --git a/internal/commands/profile/profiles/rename.go b/internal/commands/profile/profiles/rename.go index 17588c33..4e47f5a1 100644 --- a/internal/commands/profile/profiles/rename.go +++ b/internal/commands/profile/profiles/rename.go @@ -18,7 +18,7 @@ func NewCmdRename(ctx *cmd.Context) *cmd.Command { renameCmd := &cmd.Command{ Name: "rename", ShortHelp: "Rename an existing profile.", - LongHelp: "Rename an existing profile.", + LongHelp: "The `hcp profile profiles rename` command renames an existing profile.", Examples: []cmd.Example{ { Preamble: "To rename profile my-profile to new-profile, run:", diff --git a/internal/commands/profile/set.go b/internal/commands/profile/set.go index b61a24f7..b20f3c36 100644 --- a/internal/commands/profile/set.go +++ b/internal/commands/profile/set.go @@ -30,7 +30,7 @@ func NewCmdSet(ctx *cmd.Context) *cmd.Command { Name: "set", ShortHelp: "Set a HCP CLI Property.", LongHelp: heredoc.New(ctx.IO).Mustf(` - {{ template "mdCodeOrBold" "hcp profile set" }} sets the specified property in your + The {{ template "mdCodeOrBold" "hcp profile set" }} command sets the specified property in your active profile. A property governs the behavior of a specific aspect of the HCP CLI. This could be setting the organization and project to target, or configuring the default output format across commands. diff --git a/internal/commands/profile/unset.go b/internal/commands/profile/unset.go index 9ecc8773..b9cc88a2 100644 --- a/internal/commands/profile/unset.go +++ b/internal/commands/profile/unset.go @@ -23,7 +23,7 @@ func NewCmdUnset(ctx *cmd.Context) *cmd.Command { Name: "unset", ShortHelp: "Unset a HCP CLI Property.", LongHelp: heredoc.New(ctx.IO).Mustf(` - {{ template "mdCodeOrBold" "hcp profile unset" }} unsets the specified property in your active profile. + The {{ template "mdCodeOrBold" "hcp profile unset" }} command unsets the specified property in your active profile. To view all currently set properties, run {{ template "mdCodeOrBold" "hcp profile display" }}. `), diff --git a/internal/commands/projects/create.go b/internal/commands/projects/create.go index 9b9a2be0..144e3bde 100644 --- a/internal/commands/projects/create.go +++ b/internal/commands/projects/create.go @@ -35,7 +35,7 @@ func NewCmdCreate(ctx *cmd.Context, runF func(*CreateOpts) error) *cmd.Command { Name: "create", ShortHelp: "Create a new project.", LongHelp: heredoc.New(ctx.IO).Must(` - Creates a new project with the given name. The currently authenticated principal + The {{ template "mdCodeOrBold" "hcp products create" }} command creates a new project with the given name. The currently authenticated principal will be given role "admin" on the newly created project. `), Examples: []cmd.Example{ diff --git a/internal/commands/projects/delete.go b/internal/commands/projects/delete.go index 1e8e3163..c045bc98 100644 --- a/internal/commands/projects/delete.go +++ b/internal/commands/projects/delete.go @@ -25,7 +25,7 @@ func NewCmdDelete(ctx *cmd.Context, runF func(*DeleteOpts) error) *cmd.Command { Name: "delete", ShortHelp: "Delete a project.", LongHelp: heredoc.New(ctx.IO).Must(` - Delete the specified project. The project must be empty before it can be deleted. + The {{ template "mdCodeOrBold" "hcp products delete" }} command deletes the specified project. The project must be empty before it can be deleted. `), Examples: []cmd.Example{ { diff --git a/internal/commands/projects/list.go b/internal/commands/projects/list.go index 048c9791..f7bae433 100644 --- a/internal/commands/projects/list.go +++ b/internal/commands/projects/list.go @@ -24,7 +24,7 @@ func NewCmdList(ctx *cmd.Context, runF func(*ListOpts) error) *cmd.Command { cmd := &cmd.Command{ Name: "list", ShortHelp: "List HCP projects.", - LongHelp: "List HCP projects.", + LongHelp: "The `hcp products create` command lists HCP projects.", RunF: func(c *cmd.Command, args []string) error { if runF != nil { return runF(opts) diff --git a/internal/commands/projects/read.go b/internal/commands/projects/read.go index a5b52139..64a4197f 100644 --- a/internal/commands/projects/read.go +++ b/internal/commands/projects/read.go @@ -23,7 +23,7 @@ func NewCmdRead(ctx *cmd.Context, runF func(*ReadOpts) error) *cmd.Command { cmd := &cmd.Command{ Name: "read", ShortHelp: "Show metadata for the project.", - LongHelp: "Show metadata for the project.", + LongHelp: "The `hcp products read` command shows metadata for the project.", Examples: []cmd.Example{ { Preamble: "Read a project:", diff --git a/internal/commands/projects/update.go b/internal/commands/projects/update.go index 6bef015c..183c89df 100644 --- a/internal/commands/projects/update.go +++ b/internal/commands/projects/update.go @@ -23,7 +23,7 @@ func NewCmdUpdate(ctx *cmd.Context, runF func(*UpdateOpts) error) *cmd.Command { cmd := &cmd.Command{ Name: "update", ShortHelp: "Update an existing project.", - LongHelp: "Update can be used to update the name or description of an existing project.", + LongHelp: "The `hcp products update` command lets you update the name or description of an existing project.", Examples: []cmd.Example{ { Preamble: "Update a project's name and description:", diff --git a/internal/commands/version/version.go b/internal/commands/version/version.go index 3b07e482..53d15021 100644 --- a/internal/commands/version/version.go +++ b/internal/commands/version/version.go @@ -13,7 +13,7 @@ func NewCmdVersion(ctx *cmd.Context) *cmd.Command { Name: "version", ShortHelp: "Display the HCP CLI version.", LongHelp: heredoc.New(ctx.IO).Must(` - Display the HCP CLI version. + The {{ template "mdCodeOrBold" "hcp version" }} command displays the HCP CLI version. `), RunF: func(c *cmd.Command, args []string) error { fmt.Fprintln(ctx.IO.Out(), version.GetHumanVersion()) diff --git a/internal/commands/waypoint/actionconfig/action_config.go b/internal/commands/waypoint/actionconfig/action_config.go index f8673f53..0ef387b8 100644 --- a/internal/commands/waypoint/actionconfig/action_config.go +++ b/internal/commands/waypoint/actionconfig/action_config.go @@ -10,7 +10,8 @@ func NewCmdActionConfig(ctx *cmd.Context) *cmd.Command { Name: "action-config", ShortHelp: "Manage action configuration options for HCP Waypoint.", LongHelp: heredoc.New(ctx.IO).Must(` - Manage all action configuration options for HCP Waypoint. An action + The {{ template "mdCodeOrBold" "hcp waypoint action-config" }} command + group manages all action configuration options for HCP Waypoint. An action configuration is a set of options that define how an action is executed. This includes the action request type, and the action name. The action configuration is used to launch action runs depending on the Request type. diff --git a/internal/commands/waypoint/actionconfig/create.go b/internal/commands/waypoint/actionconfig/create.go index f713a48a..db941461 100644 --- a/internal/commands/waypoint/actionconfig/create.go +++ b/internal/commands/waypoint/actionconfig/create.go @@ -36,7 +36,7 @@ func NewCmdCreate(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "create", ShortHelp: "Create a new action configuration.", - LongHelp: "Create a new action configuration to be used to launch an action with.", + LongHelp: "The `hcp waypoint action-config create` command creates a new action configuration to be used to launch an action with.", RunF: func(c *cmd.Command, args []string) error { return createActionConfig(c, args, opts) }, diff --git a/internal/commands/waypoint/actionconfig/delete.go b/internal/commands/waypoint/actionconfig/delete.go index 7b56d069..1d7fd5e9 100644 --- a/internal/commands/waypoint/actionconfig/delete.go +++ b/internal/commands/waypoint/actionconfig/delete.go @@ -23,7 +23,7 @@ func NewCmdDelete(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "delete", ShortHelp: "Delete an existing action configuration.", - LongHelp: "Delete an existing action configuration. This will remove the config completely from HCP Waypoint.", + LongHelp: "The `hcp waypoint action-config delete` command deletes an existing action configuration. This will remove the config completely from HCP Waypoint.", RunF: func(c *cmd.Command, args []string) error { return deleteActionConfig(c, args, opts) }, diff --git a/internal/commands/waypoint/actionconfig/list.go b/internal/commands/waypoint/actionconfig/list.go index 586992a8..ff511b71 100644 --- a/internal/commands/waypoint/actionconfig/list.go +++ b/internal/commands/waypoint/actionconfig/list.go @@ -21,7 +21,7 @@ func NewCmdList(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "list", ShortHelp: "List all known action configurations.", - LongHelp: "List all known action configurations from HCP Waypoint.", + LongHelp: "The `hcp waypoint action-config list` command lists all known action configurations from HCP Waypoint.", RunF: func(c *cmd.Command, args []string) error { return listActionConfig(c, args, opts) }, diff --git a/internal/commands/waypoint/actionconfig/read.go b/internal/commands/waypoint/actionconfig/read.go index 8b3a52e2..145018e0 100644 --- a/internal/commands/waypoint/actionconfig/read.go +++ b/internal/commands/waypoint/actionconfig/read.go @@ -24,7 +24,7 @@ func NewCmdRead(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "read", ShortHelp: "Read more details about an action configurations.", - LongHelp: "Read more details about an action configurations.", + LongHelp: "The `hcp waypoint action-config read` command returns more details about an action configurations.", RunF: func(c *cmd.Command, args []string) error { return readActionConfig(c, args, opts) }, diff --git a/internal/commands/waypoint/actionconfig/update.go b/internal/commands/waypoint/actionconfig/update.go index 31480141..6d92c5de 100644 --- a/internal/commands/waypoint/actionconfig/update.go +++ b/internal/commands/waypoint/actionconfig/update.go @@ -37,7 +37,7 @@ func NewCmdUpdate(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "update", ShortHelp: "Update a action configuration.", - LongHelp: "Update a action configuration to be used to launch an action with.", + LongHelp: "The `hcp waypoint action-config update` command updates a action configuration to be used to launch an action with.", RunF: func(c *cmd.Command, args []string) error { return updateActionConfig(c, args, opts) }, diff --git a/internal/commands/waypoint/agent/group.go b/internal/commands/waypoint/agent/group.go index 20f4c9a3..f34fea4c 100644 --- a/internal/commands/waypoint/agent/group.go +++ b/internal/commands/waypoint/agent/group.go @@ -24,7 +24,7 @@ func NewCmdGroup(ctx *cmd.Context) *cmd.Command { Name: "group", ShortHelp: "Manage HCP Waypoint Agent groups.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp waypoint agent group" }} commands manage agent groups. + The {{ template "mdCodeOrBold" "hcp waypoint agent group" }} command group manages agent groups. `), PersistentPreRun: func(c *cmd.Command, args []string) error { return cmd.RequireOrgAndProject(ctx) diff --git a/internal/commands/waypoint/agent/group_delete.go b/internal/commands/waypoint/agent/group_delete.go index a01be5b3..6a5c6316 100644 --- a/internal/commands/waypoint/agent/group_delete.go +++ b/internal/commands/waypoint/agent/group_delete.go @@ -16,7 +16,7 @@ func NewCmdGroupDelete(ctx *cmd.Context, opts *GroupOpts) *cmd.Command { Name: "delete", ShortHelp: "Delete a HCP Waypoint Agent group.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "waypoint agent group delete" }} command delete an Agent group. + The {{ template "mdCodeOrBold" "waypoint agent group delete" }} command deletes an Agent group. `), Flags: cmd.Flags{ Local: []*cmd.Flag{ diff --git a/internal/commands/waypoint/agent/group_list.go b/internal/commands/waypoint/agent/group_list.go index 7e971f9d..572281cc 100644 --- a/internal/commands/waypoint/agent/group_list.go +++ b/internal/commands/waypoint/agent/group_list.go @@ -16,7 +16,7 @@ func NewCmdGroupList(ctx *cmd.Context, opts *GroupOpts) *cmd.Command { Name: "list", ShortHelp: "List HCP Waypoint Agent groups.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ Bold "hcp waypoint agent group list" }} command lists groups registered. + The {{ template "mdCodeOrBold" "hcp waypoint agent group list" }} command lists groups registered. `), Examples: []cmd.Example{ { diff --git a/internal/commands/waypoint/agent/run.go b/internal/commands/waypoint/agent/run.go index fe0debc6..b7e199bb 100644 --- a/internal/commands/waypoint/agent/run.go +++ b/internal/commands/waypoint/agent/run.go @@ -33,7 +33,7 @@ func NewCmdRun(ctx *cmd.Context) *cmd.Command { Name: "run", ShortHelp: "Start the Waypoint Agent.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp waypoint agent run" }} commands executes a local Waypoint Agent. + The {{ template "mdCodeOrBold" "hcp waypoint agent run" }} command executes a local Waypoint Agent. `), Flags: cmd.Flags{ Local: []*cmd.Flag{ diff --git a/internal/commands/waypoint/tfcconfig/tfc_config.go b/internal/commands/waypoint/tfcconfig/tfc_config.go index e08e9f1b..76204a99 100644 --- a/internal/commands/waypoint/tfcconfig/tfc_config.go +++ b/internal/commands/waypoint/tfcconfig/tfc_config.go @@ -13,7 +13,8 @@ func NewCmdTFCConfig(ctx *cmd.Context) *cmd.Command { Name: "tfc-config", ShortHelp: "Manage Terraform Cloud Configurations.", LongHelp: heredoc.New(ctx.IO).Must(` - Manage the set of TFC Configs. New TFC Configs can be created using + The {{ template "mdCodeOrBold" "hcp waypoint tfc-config" }} command group manages + the set of TFC Configs. New TFC Configs can be created using {{ template "mdCodeOrBold" "hcp waypoint tfc-config set" }} and existing profiles can be viewed using {{ template "mdCodeOrBold" "hcp waypoint tfc-config get" }}. `), diff --git a/internal/commands/waypoint/tfcconfig/tfc_config_create.go b/internal/commands/waypoint/tfcconfig/tfc_config_create.go index 4d8d887d..ec13f8c8 100644 --- a/internal/commands/waypoint/tfcconfig/tfc_config_create.go +++ b/internal/commands/waypoint/tfcconfig/tfc_config_create.go @@ -54,7 +54,7 @@ func NewCmdCreate(ctx *cmd.Context, runF func(opts *TFCConfigCreateOpts) error) Team token must be set in order to perform HCP Waypoint commands. - See the {{ Link "API tokens documentation" "https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens" }} to learn more. + Refer to the {{ Link "API tokens documentation" "https://developer.hashicorp.com/terraform/cloud-docs/users-teams-organizations/api-tokens" }} to learn more. HCP Waypoint requires Team level access tokens in order to run correctly. diff --git a/internal/pkg/cmd/gen_md.go b/internal/pkg/cmd/gen_md.go index 66290463..99925f27 100644 --- a/internal/pkg/cmd/gen_md.go +++ b/internal/pkg/cmd/gen_md.go @@ -70,7 +70,7 @@ func GenMarkdown(c *Command, w io.Writer, link LinkHandler) error { buf.WriteString("---\n") buf.WriteString(fmt.Sprintf("page_title: %s\n", name)) - buf.WriteString(fmt.Sprintf("description: |-\n %s\n", c.ShortHelp)) + buf.WriteString(fmt.Sprintf("description: |-\n The \"%s\" command lets you %s\n", name, (strings.ToLower(c.ShortHelp[:1]) + c.ShortHelp[1:]))) buf.WriteString("---\n\n") _, err := buf.WriteTo(w) @@ -79,7 +79,10 @@ func GenMarkdown(c *Command, w io.Writer, link LinkHandler) error { } buf.WriteString("# " + name + "\n\n") - buf.WriteString(fmt.Sprintf("%s\n\n", c.ShortHelp)) + buf.WriteString(fmt.Sprintf("Command: `%s` \n\n", name)) + + // Description + buf.WriteString(c.LongHelp + "\n\n") // Disable markdown escaping and then re-enable. This is needed because // the flags / args would otherwise generate markdown that will not render @@ -89,12 +92,6 @@ func GenMarkdown(c *Command, w io.Writer, link LinkHandler) error { buf.WriteString(fmt.Sprintf("```shell-session\n$ %s\n```\n\n", c.useLine())) mdIO.SetMD(true) - // Description - if len(c.LongHelp) > 0 { - buf.WriteString("## Description\n\n") - buf.WriteString(c.LongHelp + "\n\n") - } - // Aliases if len(c.Aliases) > 0 { buf.WriteString("## Aliases\n\n") @@ -128,7 +125,7 @@ func GenMarkdown(c *Command, w io.Writer, link LinkHandler) error { } } if len(groups) > 0 { - buf.WriteString("## Command Groups\n\n") + buf.WriteString("## Command groups\n\n") buf.WriteString(strings.Join(groups, "\n") + "\n\n") } @@ -160,7 +157,7 @@ func genMarkdownPositionalArgs(c *Command, buf *bytes.Buffer) { } cs := c.getIO().ColorScheme() - buf.WriteString("## Positional Arguments\n\n") + buf.WriteString("## Positional arguments\n\n") p := c.Args if p.Preamble != "" { fmt.Fprintln(buf, p.Preamble) @@ -172,10 +169,10 @@ func genMarkdownPositionalArgs(c *Command, buf *bytes.Buffer) { if a.Repeatable { repeatable = fmt.Sprintf(" [%s ...]", nameUpper) } - fmt.Fprintf(buf, "`%s%s`\n\n", nameUpper, repeatable) + fmt.Fprintf(buf, "- `%s%s` - ", nameUpper, repeatable) if a.Optional { - fmt.Fprintln(buf, cs.String("Optional Argument\n").Italic().String()) + fmt.Fprintln(buf, cs.String("Optional argument\n").Italic().String()) } fmt.Fprintln(buf, a.Documentation) fmt.Fprintln(buf) @@ -185,7 +182,7 @@ func genMarkdownPositionalArgs(c *Command, buf *bytes.Buffer) { func genMarkdownFlags(c *Command, buf *bytes.Buffer) { // If we are the root command, just print global flags. if c.parent == nil && c.RunF == nil { - buf.WriteString("## Global Flags\n\n") + buf.WriteString("## Global flags\n\n") genMarkdownFlagsetUsage(c.globalFlags(), buf) } @@ -211,11 +208,11 @@ func genMarkdownFlags(c *Command, buf *bytes.Buffer) { for _, set := range flagSets { required, optional := splitRequiredFlags(set.flags) if required.HasFlags() { - buf.WriteString(fmt.Sprintf("## Required %sFlags\n\n", set.name)) + buf.WriteString(fmt.Sprintf("## Required %sflags\n\n", set.name)) genMarkdownFlagsetUsage(required, buf) if optional.HasFlags() { - buf.WriteString(fmt.Sprintf("## Optional %sFlags\n\n", set.name)) + buf.WriteString(fmt.Sprintf("## Optional %sflags\n\n", set.name)) genMarkdownFlagsetUsage(optional, buf) } } else if optional.HasFlags() { @@ -233,9 +230,9 @@ func genMarkdownFlagsetUsage(flags *pflag.FlagSet, buf *bytes.Buffer) { longDisplay := flagString(flag) if flag.Shorthand != "" && flag.ShorthandDeprecated == "" { - fmt.Fprintf(buf, "`-%s, %s`\n\n", flag.Shorthand, longDisplay) + fmt.Fprintf(buf, "- `-%s, %s` -", flag.Shorthand, longDisplay) } else { - fmt.Fprintf(buf, "`%s`\n\n", longDisplay) + fmt.Fprintf(buf, "- `%s` - ", longDisplay) } // Add the usage diff --git a/internal/pkg/cmd/gen_nav_json.go b/internal/pkg/cmd/gen_nav_json.go index 514fffc6..2da3ead3 100644 --- a/internal/pkg/cmd/gen_nav_json.go +++ b/internal/pkg/cmd/gen_nav_json.go @@ -24,7 +24,7 @@ func GenNavJSON(c *Command, w io.Writer) error { // Create the top level nav item nav := &navItem{ - Title: "Command Reference", + Title: "Commands (CLI)", Routes: root.Routes[0].Routes, } From 96c28f5c81e278e92fabd427bd8e239c60c3a8d3 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Tue, 19 Mar 2024 21:10:15 -0700 Subject: [PATCH 2/8] update all LongHelp to be consistent, fix typos --- internal/commands/auth/auth.go | 5 ++++- internal/commands/auth/login.go | 2 +- internal/commands/auth/logout.go | 2 +- internal/commands/iam/groups/members/list.go | 2 +- internal/commands/iam/iam.go | 2 +- internal/commands/organizations/iam/add_binding.go | 2 +- internal/commands/organizations/iam/delete_binding.go | 2 +- internal/commands/organizations/iam/read_policy.go | 5 ++++- internal/commands/organizations/iam/set_policy.go | 2 +- internal/commands/organizations/list.go | 5 ++++- internal/commands/organizations/read.go | 5 ++++- internal/commands/profile/profiles/activate.go | 5 ++++- internal/commands/profile/profiles/create.go | 2 +- internal/commands/profile/profiles/delete.go | 2 +- internal/commands/profile/profiles/list.go | 5 ++++- internal/commands/profile/profiles/profiles.go | 4 ++-- internal/commands/profile/profiles/rename.go | 5 ++++- internal/commands/projects/create.go | 2 +- internal/commands/projects/delete.go | 2 +- internal/commands/projects/list.go | 5 ++++- internal/commands/projects/read.go | 5 ++++- internal/commands/projects/update.go | 4 +++- internal/commands/version/version.go | 2 +- internal/commands/waypoint/actionconfig/action_config.go | 2 +- internal/commands/waypoint/actionconfig/create.go | 5 ++++- internal/commands/waypoint/actionconfig/delete.go | 5 ++++- internal/commands/waypoint/actionconfig/list.go | 5 ++++- internal/commands/waypoint/actionconfig/read.go | 5 ++++- internal/commands/waypoint/actionconfig/update.go | 5 ++++- internal/commands/waypoint/tfcconfig/tfc_config.go | 2 +- internal/pkg/heredoc/heredoc.go | 2 +- 31 files changed, 76 insertions(+), 32 deletions(-) diff --git a/internal/commands/auth/auth.go b/internal/commands/auth/auth.go index 0ed45532..0d377a94 100644 --- a/internal/commands/auth/auth.go +++ b/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: "The `hcp auth` command group lets you 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:", diff --git a/internal/commands/auth/login.go b/internal/commands/auth/login.go index 75f983a6..bbba6092 100644 --- a/internal/commands/auth/login.go +++ b/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(` - The {{ template "mdCodeOrBold" "hcp auth login" }} command lets you login 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. diff --git a/internal/commands/auth/logout.go b/internal/commands/auth/logout.go index 8df72d63..66757325 100644 --- a/internal/commands/auth/logout.go +++ b/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{ { diff --git a/internal/commands/iam/groups/members/list.go b/internal/commands/iam/groups/members/list.go index bdf5de39..eff1080b 100644 --- a/internal/commands/iam/groups/members/list.go +++ b/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. `), diff --git a/internal/commands/iam/iam.go b/internal/commands/iam/iam.go index d4b536b5..78a2a4eb 100644 --- a/internal/commands/iam/iam.go +++ b/internal/commands/iam/iam.go @@ -13,7 +13,7 @@ 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 including users, groups, and service principals. diff --git a/internal/commands/organizations/iam/add_binding.go b/internal/commands/organizations/iam/add_binding.go index ffb60f5a..f248068b 100644 --- a/internal/commands/organizations/iam/add_binding.go +++ b/internal/commands/organizations/iam/add_binding.go @@ -26,7 +26,7 @@ func NewCmdAddBinding(ctx *cmd.Context, runF func(*AddBindingOpts) error) *cmd.C Name: "add-binding", ShortHelp: "Add an IAM policy binding for the organization.", LongHelp: heredoc.New(ctx.IO).Must(` - Add an IAM policy binding for the organization. A binding grants the + The {{ template "mdCodeOrBold" "hcp organizations iam add-binding" }} command adds an IAM policy binding for the organization. A binding grants the specified principal the given role on the organization. To view the available roles to bind, run diff --git a/internal/commands/organizations/iam/delete_binding.go b/internal/commands/organizations/iam/delete_binding.go index 00b1f3cd..4db6f82a 100644 --- a/internal/commands/organizations/iam/delete_binding.go +++ b/internal/commands/organizations/iam/delete_binding.go @@ -23,7 +23,7 @@ func NewCmdDeleteBinding(ctx *cmd.Context, runF func(*DeleteBindingOpts) error) Name: "delete-binding", ShortHelp: "Delete an IAM policy binding for the organization.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp organizations iam delete-binding" }} command deletes an IAM policy binding for the organization. A binding consists of a + The {{ template "mdCodeOrBold" "hcp organizations iam delete-binding" }} command deletes an IAM policy binding for the organization. A binding consists of a principal and a role. To view the existing role bindings, run {{ template "mdCodeOrBold" "hcp organizations iam read-policy" }}. diff --git a/internal/commands/organizations/iam/read_policy.go b/internal/commands/organizations/iam/read_policy.go index ac79add7..4d9cf86b 100644 --- a/internal/commands/organizations/iam/read_policy.go +++ b/internal/commands/organizations/iam/read_policy.go @@ -8,6 +8,7 @@ import ( "github.com/hashicorp/hcp/internal/pkg/api/iampolicy" "github.com/hashicorp/hcp/internal/pkg/cmd" "github.com/hashicorp/hcp/internal/pkg/format" + "github.com/hashicorp/hcp/internal/pkg/heredoc" "github.com/hashicorp/hcp/internal/pkg/iostreams" "github.com/hashicorp/hcp/internal/pkg/profile" ) @@ -25,7 +26,9 @@ func NewCmdReadPolicy(ctx *cmd.Context, runF func(*ReadPolicyOpts) error) *cmd.C cmd := &cmd.Command{ Name: "read-policy", ShortHelp: "Read the IAM policy for the organization.", - LongHelp: "The `hcp organizations iam read-policy` command reads the IAM policy for the organization.", + LongHelp: heredoc.New(ctx.IO).Must(` + The {{ template "mdCodeOrBold" "hcp organizations iam read-policy" }} command reads the IAM policy for the organization. + `), Examples: []cmd.Example{ { Preamble: "Read the IAM Policy for the organization:", diff --git a/internal/commands/organizations/iam/set_policy.go b/internal/commands/organizations/iam/set_policy.go index cf181c62..01a5ae8b 100644 --- a/internal/commands/organizations/iam/set_policy.go +++ b/internal/commands/organizations/iam/set_policy.go @@ -30,7 +30,7 @@ func NewCmdSetPolicy(ctx *cmd.Context, runF func(*SetPolicyOpts) error) *cmd.Com Name: "set-policy", ShortHelp: "Set the IAM policy for the organization.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp organizations iam set-policy" }} command sets the IAM policy for the organization. Setting the entire policy must be done + The {{ template "mdCodeOrBold" "hcp organizations iam set-policy" }} command sets the IAM policy for the organization. Setting the entire policy must be done with great care. If adding or removing a single principal from the policy, prefer using {{ template "mdCodeOrBold" "hcp organizations iam add-binding" }} and the related {{ template "mdCodeOrBold" "hcp organizations iam delete-binding" }}. diff --git a/internal/commands/organizations/list.go b/internal/commands/organizations/list.go index 7fefbea2..545041dc 100644 --- a/internal/commands/organizations/list.go +++ b/internal/commands/organizations/list.go @@ -8,6 +8,7 @@ import ( "github.com/hashicorp/hcp-sdk-go/clients/cloud-resource-manager/stable/2019-12-10/models" "github.com/hashicorp/hcp/internal/pkg/cmd" "github.com/hashicorp/hcp/internal/pkg/format" + "github.com/hashicorp/hcp/internal/pkg/heredoc" "github.com/hashicorp/hcp/internal/pkg/iostreams" "github.com/hashicorp/hcp/internal/pkg/profile" ) @@ -24,7 +25,9 @@ func NewCmdList(ctx *cmd.Context, runF func(*ListOpts) error) *cmd.Command { cmd := &cmd.Command{ Name: "list", ShortHelp: "List organizations.", - LongHelp: "The `hcp organizations list` command lists the organizations the authenticated principal is a member of.", + LongHelp: heredoc.New(ctx.IO).Must(` + "The {{ template "mdCodeOrBold" "hcp organizations list" }} command lists the organizations the authenticated principal is a member of." + `), RunF: func(c *cmd.Command, args []string) error { if runF != nil { return runF(opts) diff --git a/internal/commands/organizations/read.go b/internal/commands/organizations/read.go index e15b3636..f9ec5bfa 100644 --- a/internal/commands/organizations/read.go +++ b/internal/commands/organizations/read.go @@ -7,6 +7,7 @@ import ( "github.com/hashicorp/hcp-sdk-go/clients/cloud-resource-manager/stable/2019-12-10/client/organization_service" "github.com/hashicorp/hcp/internal/pkg/cmd" "github.com/hashicorp/hcp/internal/pkg/format" + "github.com/hashicorp/hcp/internal/pkg/heredoc" "github.com/hashicorp/hcp/internal/pkg/iostreams" "github.com/hashicorp/hcp/internal/pkg/profile" ) @@ -23,7 +24,9 @@ func NewCmdRead(ctx *cmd.Context, runF func(*ReadOpts) error) *cmd.Command { cmd := &cmd.Command{ Name: "read", ShortHelp: "Show metadata for the organization.", - LongHelp: "The `hcp organizations read` command shows metadata for the organization.", + LongHelp: heredoc.New(ctx.IO).Must(` + The {{ template "mdCodeOrBold" "hcp organizations read" }} command shows metadata for the organization. + `), Args: cmd.PositionalArguments{ Args: []cmd.PositionalArgument{ { diff --git a/internal/commands/profile/profiles/activate.go b/internal/commands/profile/profiles/activate.go index 7bd917b4..aef91b67 100644 --- a/internal/commands/profile/profiles/activate.go +++ b/internal/commands/profile/profiles/activate.go @@ -5,6 +5,7 @@ import ( "slices" "github.com/hashicorp/hcp/internal/pkg/cmd" + "github.com/hashicorp/hcp/internal/pkg/heredoc" "github.com/hashicorp/hcp/internal/pkg/iostreams" "github.com/hashicorp/hcp/internal/pkg/profile" ) @@ -16,7 +17,9 @@ func NewCmdActivate(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "activate", ShortHelp: "Activates an existing profile.", - LongHelp: "The `hcp profile profiles activate` command activates an existing profile.", + LongHelp: heredoc.New(ctx.IO).Must(` + The {{ template "mdCodeOrBold" "hcp profile profiles activate" }} command activates an existing profile. + `), Examples: []cmd.Example{ { Preamble: "To active profile my-profile, run:", diff --git a/internal/commands/profile/profiles/create.go b/internal/commands/profile/profiles/create.go index bf0a8cf3..75dca9f0 100644 --- a/internal/commands/profile/profiles/create.go +++ b/internal/commands/profile/profiles/create.go @@ -18,7 +18,7 @@ func NewCmdCreate(ctx *cmd.Context) *cmd.Command { Name: "create", ShortHelp: "Create a new HCP profile.", LongHelp: heredoc.New(ctx.IO).Mustf(` - The {{ template "mdCodeOrBold" "hcp profile profiles create" }} command creates a new named profile. + The {{ template "mdCodeOrBold" "hcp profile profiles create" }} command creates a new named profile. Profile names start with a letter and may contain lower case letters a-z, upper case letters A-Z, digits 0-9, and hyphens '-'. The maximum length for diff --git a/internal/commands/profile/profiles/delete.go b/internal/commands/profile/profiles/delete.go index b56c8afa..499025d2 100644 --- a/internal/commands/profile/profiles/delete.go +++ b/internal/commands/profile/profiles/delete.go @@ -17,7 +17,7 @@ func NewCmdDelete(ctx *cmd.Context) *cmd.Command { Name: "delete", ShortHelp: "Delete an existing HCP profile.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp profile profiles delete" }} command deletes an existing HCP profiles. If the profile is the active profile, it may not be deleted. + The {{ template "mdCodeOrBold" "hcp profile profiles delete" }} command deletes an existing HCP profiles. If the profile is the active profile, it may not be deleted. To delete the current active profile, first run {{ template "mdCodeOrBold" "hcp profile profiles activate" }} to active a different profile. diff --git a/internal/commands/profile/profiles/list.go b/internal/commands/profile/profiles/list.go index bd459925..1d296ecb 100644 --- a/internal/commands/profile/profiles/list.go +++ b/internal/commands/profile/profiles/list.go @@ -7,6 +7,7 @@ import ( "github.com/hashicorp/hcp/internal/pkg/cmd" "github.com/hashicorp/hcp/internal/pkg/format" + "github.com/hashicorp/hcp/internal/pkg/heredoc" "github.com/hashicorp/hcp/internal/pkg/iostreams" "github.com/hashicorp/hcp/internal/pkg/profile" ) @@ -19,7 +20,9 @@ func NewCmdList(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "list", ShortHelp: "List existing HCP profiles.", - LongHelp: "The `hcp profile profiles list` command lists existing HCP profiles.", + LongHelp: heredoc.New(ctx.IO).Must(` + The {{ template "mdCodeOrBold" "hcp hcp profile profiles list" }} command lists existing HCP profiles. + `), Examples: []cmd.Example{ { Preamble: "To list existing profiles, run:", diff --git a/internal/commands/profile/profiles/profiles.go b/internal/commands/profile/profiles/profiles.go index 0269f5d8..e19ca69d 100644 --- a/internal/commands/profile/profiles/profiles.go +++ b/internal/commands/profile/profiles/profiles.go @@ -18,8 +18,8 @@ func NewCmdProfiles(ctx *cmd.Context) *cmd.Command { Name: "profiles", ShortHelp: "Manage HCP profiles.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp profile profiles" }} command group lets you - manage the set of named HCP profiles. You can create new profiles using + The {{ template "mdCodeOrBold" "hcp profile profiles" }} command group manages + the set of named HCP profiles. You can create new profiles using {{ template "mdCodeOrBold" "hcp profile profiles create" }} and activate existing profiles using {{ template "mdCodeOrBold" "hcp profile profiles activate" }}. To run a single command against a profile other than the active profile, diff --git a/internal/commands/profile/profiles/rename.go b/internal/commands/profile/profiles/rename.go index 4e47f5a1..669c9b3a 100644 --- a/internal/commands/profile/profiles/rename.go +++ b/internal/commands/profile/profiles/rename.go @@ -7,6 +7,7 @@ import ( "github.com/hashicorp/hcp/internal/pkg/cmd" "github.com/hashicorp/hcp/internal/pkg/flagvalue" + "github.com/hashicorp/hcp/internal/pkg/heredoc" "github.com/hashicorp/hcp/internal/pkg/iostreams" "github.com/hashicorp/hcp/internal/pkg/profile" ) @@ -18,7 +19,9 @@ func NewCmdRename(ctx *cmd.Context) *cmd.Command { renameCmd := &cmd.Command{ Name: "rename", ShortHelp: "Rename an existing profile.", - LongHelp: "The `hcp profile profiles rename` command renames an existing profile.", + LongHelp: heredoc.New(ctx.IO).Must(` + The {{ template "mdCodeOrBold" "hcp profile profiles rename" }} command renames an existing profile. + `), Examples: []cmd.Example{ { Preamble: "To rename profile my-profile to new-profile, run:", diff --git a/internal/commands/projects/create.go b/internal/commands/projects/create.go index 144e3bde..7b071270 100644 --- a/internal/commands/projects/create.go +++ b/internal/commands/projects/create.go @@ -35,7 +35,7 @@ func NewCmdCreate(ctx *cmd.Context, runF func(*CreateOpts) error) *cmd.Command { Name: "create", ShortHelp: "Create a new project.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp products create" }} command creates a new project with the given name. The currently authenticated principal + The {{ template "mdCodeOrBold" "hcp products create" }} command creates a new project with the given name. The currently authenticated principal will be given role "admin" on the newly created project. `), Examples: []cmd.Example{ diff --git a/internal/commands/projects/delete.go b/internal/commands/projects/delete.go index c045bc98..65a29d75 100644 --- a/internal/commands/projects/delete.go +++ b/internal/commands/projects/delete.go @@ -25,7 +25,7 @@ func NewCmdDelete(ctx *cmd.Context, runF func(*DeleteOpts) error) *cmd.Command { Name: "delete", ShortHelp: "Delete a project.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp products delete" }} command deletes the specified project. The project must be empty before it can be deleted. + The {{ template "mdCodeOrBold" "hcp products delete" }} command deletes the specified project. The project must be empty before it can be deleted. `), Examples: []cmd.Example{ { diff --git a/internal/commands/projects/list.go b/internal/commands/projects/list.go index f7bae433..938b364d 100644 --- a/internal/commands/projects/list.go +++ b/internal/commands/projects/list.go @@ -8,6 +8,7 @@ import ( "github.com/hashicorp/hcp-sdk-go/clients/cloud-resource-manager/stable/2019-12-10/models" "github.com/hashicorp/hcp/internal/pkg/cmd" "github.com/hashicorp/hcp/internal/pkg/format" + "github.com/hashicorp/hcp/internal/pkg/heredoc" "github.com/hashicorp/hcp/internal/pkg/iostreams" "github.com/hashicorp/hcp/internal/pkg/profile" ) @@ -24,7 +25,9 @@ func NewCmdList(ctx *cmd.Context, runF func(*ListOpts) error) *cmd.Command { cmd := &cmd.Command{ Name: "list", ShortHelp: "List HCP projects.", - LongHelp: "The `hcp products create` command lists HCP projects.", + LongHelp: heredoc.New(ctx.IO).Must(` + The {{ template "mdCodeOrBold" "hcp products create" }} command lists HCP projects. + `), RunF: func(c *cmd.Command, args []string) error { if runF != nil { return runF(opts) diff --git a/internal/commands/projects/read.go b/internal/commands/projects/read.go index 64a4197f..3c728a35 100644 --- a/internal/commands/projects/read.go +++ b/internal/commands/projects/read.go @@ -7,6 +7,7 @@ import ( "github.com/hashicorp/hcp-sdk-go/clients/cloud-resource-manager/stable/2019-12-10/client/project_service" "github.com/hashicorp/hcp/internal/pkg/cmd" "github.com/hashicorp/hcp/internal/pkg/format" + "github.com/hashicorp/hcp/internal/pkg/heredoc" "github.com/hashicorp/hcp/internal/pkg/iostreams" "github.com/hashicorp/hcp/internal/pkg/profile" ) @@ -23,7 +24,9 @@ func NewCmdRead(ctx *cmd.Context, runF func(*ReadOpts) error) *cmd.Command { cmd := &cmd.Command{ Name: "read", ShortHelp: "Show metadata for the project.", - LongHelp: "The `hcp products read` command shows metadata for the project.", + LongHelp: heredoc.New(ctx.IO).Must(` + The {{ template "mdCodeOrBold" "hcp products read" }} command shows metadata for the project. + `), Examples: []cmd.Example{ { Preamble: "Read a project:", diff --git a/internal/commands/projects/update.go b/internal/commands/projects/update.go index 183c89df..b4340c70 100644 --- a/internal/commands/projects/update.go +++ b/internal/commands/projects/update.go @@ -23,7 +23,9 @@ func NewCmdUpdate(ctx *cmd.Context, runF func(*UpdateOpts) error) *cmd.Command { cmd := &cmd.Command{ Name: "update", ShortHelp: "Update an existing project.", - LongHelp: "The `hcp products update` command lets you update the name or description of an existing project.", + LongHelp: heredoc.New(ctx.IO).Must(` + The {{ template "mdCodeOrBold" "hcp products update" }} command shows metadata for the project. + `), Examples: []cmd.Example{ { Preamble: "Update a project's name and description:", diff --git a/internal/commands/version/version.go b/internal/commands/version/version.go index 53d15021..fac8da53 100644 --- a/internal/commands/version/version.go +++ b/internal/commands/version/version.go @@ -13,7 +13,7 @@ func NewCmdVersion(ctx *cmd.Context) *cmd.Command { Name: "version", ShortHelp: "Display the HCP CLI version.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp version" }} command displays the HCP CLI version. + The {{ template "mdCodeOrBold" "hcp version" }} command displays the HCP CLI version. `), RunF: func(c *cmd.Command, args []string) error { fmt.Fprintln(ctx.IO.Out(), version.GetHumanVersion()) diff --git a/internal/commands/waypoint/actionconfig/action_config.go b/internal/commands/waypoint/actionconfig/action_config.go index 0ef387b8..64c62174 100644 --- a/internal/commands/waypoint/actionconfig/action_config.go +++ b/internal/commands/waypoint/actionconfig/action_config.go @@ -10,7 +10,7 @@ func NewCmdActionConfig(ctx *cmd.Context) *cmd.Command { Name: "action-config", ShortHelp: "Manage action configuration options for HCP Waypoint.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp waypoint action-config" }} command + The {{ template "mdCodeOrBold" "hcp waypoint action-config" }} command group manages all action configuration options for HCP Waypoint. An action configuration is a set of options that define how an action is executed. This includes the action request type, and the action name. The action diff --git a/internal/commands/waypoint/actionconfig/create.go b/internal/commands/waypoint/actionconfig/create.go index db941461..68dfff24 100644 --- a/internal/commands/waypoint/actionconfig/create.go +++ b/internal/commands/waypoint/actionconfig/create.go @@ -10,6 +10,7 @@ import ( "github.com/hashicorp/hcp/internal/commands/waypoint/opts" "github.com/hashicorp/hcp/internal/pkg/cmd" "github.com/hashicorp/hcp/internal/pkg/flagvalue" + "github.com/hashicorp/hcp/internal/pkg/heredoc" ) type CreateOpts struct { @@ -36,7 +37,9 @@ func NewCmdCreate(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "create", ShortHelp: "Create a new action configuration.", - LongHelp: "The `hcp waypoint action-config create` command creates a new action configuration to be used to launch an action with.", + LongHelp: heredoc.New(ctx.IO).Must(` + The {{ template "mdCodeOrBold" "hcp waypoint action-config create" }} command creates a new action configuration to be used to launch an action with. + `), RunF: func(c *cmd.Command, args []string) error { return createActionConfig(c, args, opts) }, diff --git a/internal/commands/waypoint/actionconfig/delete.go b/internal/commands/waypoint/actionconfig/delete.go index 1d7fd5e9..666f0177 100644 --- a/internal/commands/waypoint/actionconfig/delete.go +++ b/internal/commands/waypoint/actionconfig/delete.go @@ -7,6 +7,7 @@ import ( "github.com/hashicorp/hcp/internal/commands/waypoint/opts" "github.com/hashicorp/hcp/internal/pkg/cmd" "github.com/hashicorp/hcp/internal/pkg/flagvalue" + "github.com/hashicorp/hcp/internal/pkg/heredoc" ) type DeleteOpts struct { @@ -23,7 +24,9 @@ func NewCmdDelete(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "delete", ShortHelp: "Delete an existing action configuration.", - LongHelp: "The `hcp waypoint action-config delete` command deletes an existing action configuration. This will remove the config completely from HCP Waypoint.", + LongHelp: heredoc.New(ctx.IO).Must(` + The {{ template "mdCodeOrBold" "hcp waypoint action-config delete" }} command deletes an existing action configuration. This will remove the config completely from HCP Waypoint. + `), RunF: func(c *cmd.Command, args []string) error { return deleteActionConfig(c, args, opts) }, diff --git a/internal/commands/waypoint/actionconfig/list.go b/internal/commands/waypoint/actionconfig/list.go index ff511b71..0a2c2a0b 100644 --- a/internal/commands/waypoint/actionconfig/list.go +++ b/internal/commands/waypoint/actionconfig/list.go @@ -7,6 +7,7 @@ import ( "github.com/hashicorp/hcp/internal/commands/waypoint/opts" "github.com/hashicorp/hcp/internal/pkg/cmd" "github.com/hashicorp/hcp/internal/pkg/format" + "github.com/hashicorp/hcp/internal/pkg/heredoc" ) type ListOpts struct { @@ -21,7 +22,9 @@ func NewCmdList(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "list", ShortHelp: "List all known action configurations.", - LongHelp: "The `hcp waypoint action-config list` command lists all known action configurations from HCP Waypoint.", + LongHelp: heredoc.New(ctx.IO).Must(` + The {{ template "mdCodeOrBold" "hcp waypoint action-config list" }} command lists all known action configurations from HCP Waypoint. + `), RunF: func(c *cmd.Command, args []string) error { return listActionConfig(c, args, opts) }, diff --git a/internal/commands/waypoint/actionconfig/read.go b/internal/commands/waypoint/actionconfig/read.go index 145018e0..7d8ae6ad 100644 --- a/internal/commands/waypoint/actionconfig/read.go +++ b/internal/commands/waypoint/actionconfig/read.go @@ -8,6 +8,7 @@ import ( "github.com/hashicorp/hcp/internal/pkg/cmd" "github.com/hashicorp/hcp/internal/pkg/flagvalue" "github.com/hashicorp/hcp/internal/pkg/format" + "github.com/hashicorp/hcp/internal/pkg/heredoc" ) type ReadOpts struct { @@ -24,7 +25,9 @@ func NewCmdRead(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "read", ShortHelp: "Read more details about an action configurations.", - LongHelp: "The `hcp waypoint action-config read` command returns more details about an action configurations.", + LongHelp: heredoc.New(ctx.IO).Must(` + The {{ template "mdCodeOrBold" "hcp waypoint action-config read" }} command returns more details about an action configurations. + `), RunF: func(c *cmd.Command, args []string) error { return readActionConfig(c, args, opts) }, diff --git a/internal/commands/waypoint/actionconfig/update.go b/internal/commands/waypoint/actionconfig/update.go index 6d92c5de..99d963c3 100644 --- a/internal/commands/waypoint/actionconfig/update.go +++ b/internal/commands/waypoint/actionconfig/update.go @@ -11,6 +11,7 @@ import ( "github.com/hashicorp/hcp/internal/pkg/cmd" "github.com/hashicorp/hcp/internal/pkg/flagvalue" "github.com/hashicorp/hcp/internal/pkg/format" + "github.com/hashicorp/hcp/internal/pkg/heredoc" ) type UpdateOpts struct { @@ -37,7 +38,9 @@ func NewCmdUpdate(ctx *cmd.Context) *cmd.Command { cmd := &cmd.Command{ Name: "update", ShortHelp: "Update a action configuration.", - LongHelp: "The `hcp waypoint action-config update` command updates a action configuration to be used to launch an action with.", + LongHelp: heredoc.New(ctx.IO).Must(` + The {{ template "mdCodeOrBold" "hcp waypoint action-config update" }} command updates a action configuration to be used to launch an action with. + `), RunF: func(c *cmd.Command, args []string) error { return updateActionConfig(c, args, opts) }, diff --git a/internal/commands/waypoint/tfcconfig/tfc_config.go b/internal/commands/waypoint/tfcconfig/tfc_config.go index 76204a99..a3232211 100644 --- a/internal/commands/waypoint/tfcconfig/tfc_config.go +++ b/internal/commands/waypoint/tfcconfig/tfc_config.go @@ -13,7 +13,7 @@ func NewCmdTFCConfig(ctx *cmd.Context) *cmd.Command { Name: "tfc-config", ShortHelp: "Manage Terraform Cloud Configurations.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp waypoint tfc-config" }} command group manages + The {{ template "mdCodeOrBold" "hcp waypoint tfc-config" }} command group manages the set of TFC Configs. New TFC Configs can be created using {{ template "mdCodeOrBold" "hcp waypoint tfc-config set" }} and existing profiles can be viewed using {{ template "mdCodeOrBold" "hcp waypoint tfc-config get" }}. diff --git a/internal/pkg/heredoc/heredoc.go b/internal/pkg/heredoc/heredoc.go index ac00640d..8b7a00a6 100644 --- a/internal/pkg/heredoc/heredoc.go +++ b/internal/pkg/heredoc/heredoc.go @@ -133,7 +133,7 @@ func (f *Formatter) Docf(tmpl string, args ...any) (string, error) { // - mdCodeOrBold: If the output is markdown, it will return the string in a // code stanza. Otherwise, it will return the string in bold. // An example usage is: -// {{ template "mdCodeOrBold" "hcp projects iam read-policy --format=json" }} +// {{ template "mdCodeOrBold" "hcp projects iam read-policy --format=json" }} // // After rendering the template following manipulations are made: // - The text is dedented. This allows you to use a Go string literal and not From 77cab1d0f2db85af85f335ff9a40c706fd592079 Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Wed, 20 Mar 2024 09:35:47 -0700 Subject: [PATCH 3/8] Small tweaks to line length --- internal/commands/iam/serviceprincipals/sps.go | 3 ++- internal/commands/organizations/iam/add_binding.go | 5 +++-- internal/commands/organizations/iam/delete_binding.go | 5 +++-- internal/commands/organizations/iam/set_policy.go | 3 ++- internal/commands/organizations/list.go | 3 ++- internal/commands/profile/init.go | 7 ++++--- internal/commands/profile/profiles/delete.go | 4 +++- internal/commands/projects/create.go | 3 ++- internal/commands/projects/delete.go | 4 +++- internal/commands/projects/iam/set_policy.go | 10 ++++++++-- internal/commands/waypoint/actionconfig/create.go | 4 +++- internal/commands/waypoint/actionconfig/delete.go | 4 +++- internal/commands/waypoint/actionconfig/list.go | 3 ++- internal/commands/waypoint/actionconfig/read.go | 3 ++- internal/commands/waypoint/actionconfig/update.go | 4 +++- internal/pkg/heredoc/heredoc.go | 2 +- 16 files changed, 46 insertions(+), 21 deletions(-) diff --git a/internal/commands/iam/serviceprincipals/sps.go b/internal/commands/iam/serviceprincipals/sps.go index 903f0281..90916b0b 100644 --- a/internal/commands/iam/serviceprincipals/sps.go +++ b/internal/commands/iam/serviceprincipals/sps.go @@ -19,7 +19,8 @@ func NewCmdServicePrincipals(ctx *cmd.Context) *cmd.Command { 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. Refer to 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{ { diff --git a/internal/commands/organizations/iam/add_binding.go b/internal/commands/organizations/iam/add_binding.go index f248068b..e0303880 100644 --- a/internal/commands/organizations/iam/add_binding.go +++ b/internal/commands/organizations/iam/add_binding.go @@ -26,8 +26,9 @@ func NewCmdAddBinding(ctx *cmd.Context, runF func(*AddBindingOpts) error) *cmd.C Name: "add-binding", ShortHelp: "Add an IAM policy binding for the organization.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp organizations iam add-binding" }} command adds an IAM policy binding for the organization. A binding grants the - specified principal the given role on the organization. + The {{ template "mdCodeOrBold" "hcp organizations iam add-binding" }} + command adds an IAM policy binding for the organization. A binding + grants the specified principal the given role on the organization. To view the available roles to bind, run {{ template "mdCodeOrBold" "hcp iam roles list" }}. diff --git a/internal/commands/organizations/iam/delete_binding.go b/internal/commands/organizations/iam/delete_binding.go index 4db6f82a..5bdc1746 100644 --- a/internal/commands/organizations/iam/delete_binding.go +++ b/internal/commands/organizations/iam/delete_binding.go @@ -23,8 +23,9 @@ func NewCmdDeleteBinding(ctx *cmd.Context, runF func(*DeleteBindingOpts) error) Name: "delete-binding", ShortHelp: "Delete an IAM policy binding for the organization.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp organizations iam delete-binding" }} command deletes an IAM policy binding for the organization. A binding consists of a - principal and a role. + The {{ template "mdCodeOrBold" "hcp organizations iam delete-binding" }} + command deletes an IAM policy binding for the organization. A binding + consists of a principal and a role. To view the existing role bindings, run {{ template "mdCodeOrBold" "hcp organizations iam read-policy" }}. `), diff --git a/internal/commands/organizations/iam/set_policy.go b/internal/commands/organizations/iam/set_policy.go index 01a5ae8b..45c61da8 100644 --- a/internal/commands/organizations/iam/set_policy.go +++ b/internal/commands/organizations/iam/set_policy.go @@ -30,7 +30,8 @@ func NewCmdSetPolicy(ctx *cmd.Context, runF func(*SetPolicyOpts) error) *cmd.Com Name: "set-policy", ShortHelp: "Set the IAM policy for the organization.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp organizations iam set-policy" }} command sets the IAM policy for the organization. Setting the entire policy must be done +The {{ template "mdCodeOrBold" "hcp organizations iam set-policy" }} command sets +the IAM policy for the organization. Setting the entire policy must be done with great care. If adding or removing a single principal from the policy, prefer using {{ template "mdCodeOrBold" "hcp organizations iam add-binding" }} and the related {{ template "mdCodeOrBold" "hcp organizations iam delete-binding" }}. diff --git a/internal/commands/organizations/list.go b/internal/commands/organizations/list.go index 545041dc..df78c5a2 100644 --- a/internal/commands/organizations/list.go +++ b/internal/commands/organizations/list.go @@ -26,7 +26,8 @@ func NewCmdList(ctx *cmd.Context, runF func(*ListOpts) error) *cmd.Command { Name: "list", ShortHelp: "List organizations.", LongHelp: heredoc.New(ctx.IO).Must(` - "The {{ template "mdCodeOrBold" "hcp organizations list" }} command lists the organizations the authenticated principal is a member of." + "The {{ template "mdCodeOrBold" "hcp organizations list" }} command + lists the organizations the authenticated principal is a member of." `), RunF: func(c *cmd.Command, args []string) error { if runF != nil { diff --git a/internal/commands/profile/init.go b/internal/commands/profile/init.go index 1f62599f..31e2627b 100644 --- a/internal/commands/profile/init.go +++ b/internal/commands/profile/init.go @@ -32,9 +32,10 @@ func NewCmdInit(ctx *cmd.Context) *cmd.Command { Name: "init", ShortHelp: "Initialize the current profile.", LongHelp: heredoc.New(ctx.IO).Mustf(` - The {{ template "mdCodeOrBold" "hcp profile init" }} command configures the HCP CLI to run commands against the correct context; namely against the - desired organization and project ID. This command is interactive. To set configuration using - non-interactively prefer using {{ template "mdCodeOrBold" "hcp profile set" }}. + The {{ template "mdCodeOrBold" "hcp profile init" }} command configures + the HCP CLI to run commands against the correct context; namely against + the desired organization and project ID. This command is interactive. To + set configuration using non-interactively prefer using {{ template "mdCodeOrBold" "hcp profile set" }}. For a list of all available options, run {{ template "mdCodeOrBold" "hcp config --help" }}. `), diff --git a/internal/commands/profile/profiles/delete.go b/internal/commands/profile/profiles/delete.go index 499025d2..4fa4e6d6 100644 --- a/internal/commands/profile/profiles/delete.go +++ b/internal/commands/profile/profiles/delete.go @@ -17,7 +17,9 @@ func NewCmdDelete(ctx *cmd.Context) *cmd.Command { Name: "delete", ShortHelp: "Delete an existing HCP profile.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp profile profiles delete" }} command deletes an existing HCP profiles. If the profile is the active profile, it may not be deleted. + The {{ template "mdCodeOrBold" "hcp profile profiles delete" }} command + deletes an existing HCP profiles. If the profile is the active profile, + it may not be deleted. To delete the current active profile, first run {{ template "mdCodeOrBold" "hcp profile profiles activate" }} to active a different profile. diff --git a/internal/commands/projects/create.go b/internal/commands/projects/create.go index 7b071270..687ad723 100644 --- a/internal/commands/projects/create.go +++ b/internal/commands/projects/create.go @@ -35,7 +35,8 @@ func NewCmdCreate(ctx *cmd.Context, runF func(*CreateOpts) error) *cmd.Command { Name: "create", ShortHelp: "Create a new project.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp products create" }} command creates a new project with the given name. The currently authenticated principal + The {{ template "mdCodeOrBold" "hcp products create" }} command creates + a new project with the given name. The currently authenticated principal will be given role "admin" on the newly created project. `), Examples: []cmd.Example{ diff --git a/internal/commands/projects/delete.go b/internal/commands/projects/delete.go index 65a29d75..2e741e18 100644 --- a/internal/commands/projects/delete.go +++ b/internal/commands/projects/delete.go @@ -25,7 +25,9 @@ func NewCmdDelete(ctx *cmd.Context, runF func(*DeleteOpts) error) *cmd.Command { Name: "delete", ShortHelp: "Delete a project.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp products delete" }} command deletes the specified project. The project must be empty before it can be deleted. + The {{ template "mdCodeOrBold" "hcp products delete" }} command deletes + the specified project. The project must be empty before it can be + deleted. `), Examples: []cmd.Example{ { diff --git a/internal/commands/projects/iam/set_policy.go b/internal/commands/projects/iam/set_policy.go index 5ebc9aaa..4e7f182f 100644 --- a/internal/commands/projects/iam/set_policy.go +++ b/internal/commands/projects/iam/set_policy.go @@ -29,8 +29,14 @@ func NewCmdSetPolicy(ctx *cmd.Context, runF func(*SetPolicyOpts) error) *cmd.Com Name: "set-policy", ShortHelp: "Set the IAM policy for a project.", LongHelp: heredoc.New(ctx.IO).Must(` -Sets the IAM policy for a project, given a project ID and a file encoded in -JSON that contains the IAM policy. +The {{ template "mdCodeOrBold" "hcp projects iam set-policy" }} command sets +the IAM policy for the project, given a project ID and a file encoded in +JSON that contains the IAM policy. If adding or removing a single principal from +the policy, prefer using {{ template "mdCodeOrBold" "hcp projects iam add-binding" }} +and the related {{ template "mdCodeOrBold" "hcp projects iam delete-binding" }}. + +The policy file is expected to be a file encoded in JSON that +contains the IAM policy. The format for the policy JSON file is an object with the following format: diff --git a/internal/commands/waypoint/actionconfig/create.go b/internal/commands/waypoint/actionconfig/create.go index 68dfff24..6c87321d 100644 --- a/internal/commands/waypoint/actionconfig/create.go +++ b/internal/commands/waypoint/actionconfig/create.go @@ -38,7 +38,9 @@ func NewCmdCreate(ctx *cmd.Context) *cmd.Command { Name: "create", ShortHelp: "Create a new action configuration.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp waypoint action-config create" }} command creates a new action configuration to be used to launch an action with. + The {{ template "mdCodeOrBold" "hcp waypoint action-config create" }} + command creates a new action configuration to be used to launch an + action with. `), RunF: func(c *cmd.Command, args []string) error { return createActionConfig(c, args, opts) diff --git a/internal/commands/waypoint/actionconfig/delete.go b/internal/commands/waypoint/actionconfig/delete.go index 666f0177..cc8f0eb1 100644 --- a/internal/commands/waypoint/actionconfig/delete.go +++ b/internal/commands/waypoint/actionconfig/delete.go @@ -25,7 +25,9 @@ func NewCmdDelete(ctx *cmd.Context) *cmd.Command { Name: "delete", ShortHelp: "Delete an existing action configuration.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp waypoint action-config delete" }} command deletes an existing action configuration. This will remove the config completely from HCP Waypoint. + The {{ template "mdCodeOrBold" "hcp waypoint action-config delete" }} + command deletes an existing action configuration. This will remove the + config completely from HCP Waypoint. `), RunF: func(c *cmd.Command, args []string) error { return deleteActionConfig(c, args, opts) diff --git a/internal/commands/waypoint/actionconfig/list.go b/internal/commands/waypoint/actionconfig/list.go index 0a2c2a0b..8a2c7b92 100644 --- a/internal/commands/waypoint/actionconfig/list.go +++ b/internal/commands/waypoint/actionconfig/list.go @@ -23,7 +23,8 @@ func NewCmdList(ctx *cmd.Context) *cmd.Command { Name: "list", ShortHelp: "List all known action configurations.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp waypoint action-config list" }} command lists all known action configurations from HCP Waypoint. + The {{ template "mdCodeOrBold" "hcp waypoint action-config list" }} + command lists all known action configurations from HCP Waypoint. `), RunF: func(c *cmd.Command, args []string) error { return listActionConfig(c, args, opts) diff --git a/internal/commands/waypoint/actionconfig/read.go b/internal/commands/waypoint/actionconfig/read.go index 7d8ae6ad..805c2208 100644 --- a/internal/commands/waypoint/actionconfig/read.go +++ b/internal/commands/waypoint/actionconfig/read.go @@ -26,7 +26,8 @@ func NewCmdRead(ctx *cmd.Context) *cmd.Command { Name: "read", ShortHelp: "Read more details about an action configurations.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp waypoint action-config read" }} command returns more details about an action configurations. + The {{ template "mdCodeOrBold" "hcp waypoint action-config read" }} + command returns more details about an action configurations. `), RunF: func(c *cmd.Command, args []string) error { return readActionConfig(c, args, opts) diff --git a/internal/commands/waypoint/actionconfig/update.go b/internal/commands/waypoint/actionconfig/update.go index 99d963c3..b7abe587 100644 --- a/internal/commands/waypoint/actionconfig/update.go +++ b/internal/commands/waypoint/actionconfig/update.go @@ -39,7 +39,9 @@ func NewCmdUpdate(ctx *cmd.Context) *cmd.Command { Name: "update", ShortHelp: "Update a action configuration.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp waypoint action-config update" }} command updates a action configuration to be used to launch an action with. + The {{ template "mdCodeOrBold" "hcp waypoint action-config update" }} + command updates a action configuration to be used to launch an action + with. `), RunF: func(c *cmd.Command, args []string) error { return updateActionConfig(c, args, opts) diff --git a/internal/pkg/heredoc/heredoc.go b/internal/pkg/heredoc/heredoc.go index 8b7a00a6..ac00640d 100644 --- a/internal/pkg/heredoc/heredoc.go +++ b/internal/pkg/heredoc/heredoc.go @@ -133,7 +133,7 @@ func (f *Formatter) Docf(tmpl string, args ...any) (string, error) { // - mdCodeOrBold: If the output is markdown, it will return the string in a // code stanza. Otherwise, it will return the string in bold. // An example usage is: -// {{ template "mdCodeOrBold" "hcp projects iam read-policy --format=json" }} +// {{ template "mdCodeOrBold" "hcp projects iam read-policy --format=json" }} // // After rendering the template following manipulations are made: // - The text is dedented. This allows you to use a Go string literal and not From edca4ca0620f614c3e49edd18e2f8cf5e68c884f Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 20 Mar 2024 21:31:35 -0700 Subject: [PATCH 4/8] Add indents to all new lines in arg/flag descriptions so they render properly in docs --- internal/pkg/cmd/gen_md.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/internal/pkg/cmd/gen_md.go b/internal/pkg/cmd/gen_md.go index 99925f27..6b33c708 100644 --- a/internal/pkg/cmd/gen_md.go +++ b/internal/pkg/cmd/gen_md.go @@ -174,7 +174,7 @@ func genMarkdownPositionalArgs(c *Command, buf *bytes.Buffer) { if a.Optional { fmt.Fprintln(buf, cs.String("Optional argument\n").Italic().String()) } - fmt.Fprintln(buf, a.Documentation) + fmt.Fprintln(buf, strings.ReplaceAll(a.Documentation, "\n", "\n\t")) fmt.Fprintln(buf) } } @@ -236,6 +236,6 @@ func genMarkdownFlagsetUsage(flags *pflag.FlagSet, buf *bytes.Buffer) { } // Add the usage - fmt.Fprintf(buf, "%s\n\n", flag.Usage) + fmt.Fprintf(buf, "%s\n\n", strings.ReplaceAll(flag.Usage, "\n", "\n\t")) }) } From a6fd61f442b35f719fb2618dc8250cb5814d5a35 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Wed, 20 Mar 2024 22:48:34 -0700 Subject: [PATCH 5/8] update descriptions so style is consistent, fix typos --- README.md | 2 +- internal/commands/auth/auth.go | 2 +- internal/commands/auth/print_access_token.go | 3 +- internal/commands/iam/groups/groups.go | 2 +- .../commands/iam/groups/members/members.go | 2 +- internal/commands/iam/iam.go | 2 +- .../commands/iam/serviceprincipals/create.go | 4 +- .../iam/serviceprincipals/keys/create.go | 5 +- .../iam/serviceprincipals/keys/list.go | 5 +- .../commands/iam/serviceprincipals/list.go | 3 +- .../commands/iam/serviceprincipals/read.go | 5 +- .../commands/iam/serviceprincipals/sps.go | 2 +- internal/commands/iam/users/users.go | 2 +- .../workloadidentityproviders/create_aws.go | 12 +- .../create_cred_file.go | 106 +++++++++++------- .../workloadidentityproviders/create_oidc.go | 14 ++- .../iam/workloadidentityproviders/list.go | 2 +- .../iam/workloadidentityproviders/wips.go | 2 +- .../commands/organizations/iam/add_binding.go | 2 +- .../organizations/iam/delete_binding.go | 2 +- internal/commands/organizations/list.go | 4 +- .../commands/profile/profiles/activate.go | 6 +- internal/commands/profile/profiles/rename.go | 7 +- internal/commands/profile/property_docs.go | 7 +- internal/commands/projects/create.go | 2 +- internal/commands/projects/delete.go | 2 +- internal/commands/projects/iam/add_binding.go | 5 +- .../commands/projects/iam/delete_binding.go | 5 +- internal/commands/projects/iam/iam.go | 2 +- internal/commands/projects/iam/read_policy.go | 4 +- internal/commands/projects/list.go | 2 +- internal/commands/projects/read.go | 2 +- internal/commands/projects/update.go | 2 +- internal/commands/waypoint/agent/agent.go | 4 +- internal/commands/waypoint/waypoint.go | 4 +- internal/pkg/cmd/gen_md.go | 6 +- 36 files changed, 140 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 61a5b01d..6c1990a1 100644 --- a/README.md +++ b/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") diff --git a/internal/commands/auth/auth.go b/internal/commands/auth/auth.go index 0d377a94..762b7881 100644 --- a/internal/commands/auth/auth.go +++ b/internal/commands/auth/auth.go @@ -10,7 +10,7 @@ func NewCmdAuth(ctx *cmd.Context) *cmd.Command { Name: "auth", ShortHelp: "Authenticate to HCP.", LongHelp: heredoc.New(ctx.IO).Must(` - "The {{ template "mdCodeOrBold" "hcp auth" }} command group lets you manage authentication to HCP." + The {{ template "mdCodeOrBold" "hcp auth" }} command group lets you manage authentication to HCP. `), Examples: []cmd.Example{ { diff --git a/internal/commands/auth/print_access_token.go b/internal/commands/auth/print_access_token.go index b8fba97d..68298207 100644 --- a/internal/commands/auth/print_access_token.go +++ b/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 " }} HTTP header when manually making API requests. diff --git a/internal/commands/iam/groups/groups.go b/internal/commands/iam/groups/groups.go index 2f267379..6b19cbbd 100644 --- a/internal/commands/iam/groups/groups.go +++ b/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 diff --git a/internal/commands/iam/groups/members/members.go b/internal/commands/iam/groups/members/members.go index 7dc1449e..e9cfd3e3 100644 --- a/internal/commands/iam/groups/members/members.go +++ b/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. `), } diff --git a/internal/commands/iam/iam.go b/internal/commands/iam/iam.go index 78a2a4eb..a24c76ec 100644 --- a/internal/commands/iam/iam.go +++ b/internal/commands/iam/iam.go @@ -15,7 +15,7 @@ func NewCmdIam(ctx *cmd.Context) *cmd.Command { Name: "iam", 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 diff --git a/internal/commands/iam/serviceprincipals/create.go b/internal/commands/iam/serviceprincipals/create.go index 08a3383d..0f3884df 100644 --- a/internal/commands/iam/serviceprincipals/create.go +++ b/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{ { diff --git a/internal/commands/iam/serviceprincipals/keys/create.go b/internal/commands/iam/serviceprincipals/keys/create.go index 479d15d5..268d901d 100644 --- a/internal/commands/iam/serviceprincipals/keys/create.go +++ b/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{ { diff --git a/internal/commands/iam/serviceprincipals/keys/list.go b/internal/commands/iam/serviceprincipals/keys/list.go index cae16822..7615f076 100644 --- a/internal/commands/iam/serviceprincipals/keys/list.go +++ b/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{ { diff --git a/internal/commands/iam/serviceprincipals/list.go b/internal/commands/iam/serviceprincipals/list.go index 752422c8..d37019b3 100644 --- a/internal/commands/iam/serviceprincipals/list.go +++ b/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 { diff --git a/internal/commands/iam/serviceprincipals/read.go b/internal/commands/iam/serviceprincipals/read.go index 929f6606..ddbe70b8 100644 --- a/internal/commands/iam/serviceprincipals/read.go +++ b/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{ { diff --git a/internal/commands/iam/serviceprincipals/sps.go b/internal/commands/iam/serviceprincipals/sps.go index 90916b0b..df777e6e 100644 --- a/internal/commands/iam/serviceprincipals/sps.go +++ b/internal/commands/iam/serviceprincipals/sps.go @@ -12,7 +12,7 @@ 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 diff --git a/internal/commands/iam/users/users.go b/internal/commands/iam/users/users.go index e824eb2f..ee44bffe 100644 --- a/internal/commands/iam/users/users.go +++ b/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. `), } diff --git a/internal/commands/iam/workloadidentityproviders/create_aws.go b/internal/commands/iam/workloadidentityproviders/create_aws.go index 7e60d699..d1a9a2bd 100644 --- a/internal/commands/iam/workloadidentityproviders/create_aws.go +++ b/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,10 +101,10 @@ 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, refer to the diff --git a/internal/commands/iam/workloadidentityproviders/create_cred_file.go b/internal/commands/iam/workloadidentityproviders/create_cred_file.go index cb12d51c..9244b388 100644 --- a/internal/commands/iam/workloadidentityproviders/create_cred_file.go +++ b/internal/commands/iam/workloadidentityproviders/create_cred_file.go @@ -60,9 +60,10 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), Examples: []cmd.Example{ { - Preamble: `Create a credential file for an AWS workload:`, + Preamble: heredoc.New(ctx.IO).Must(` + Create a credential file for an AWS workload. If the AWS instance metadata service is using version 1, you must set the + {{ template "mdCodeOrBold" "--imdsv1" }} flag.`), Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` - # Set the --imdsv1 flag if the AWS instance metadata service is using version 1. $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/aws \ --aws \ @@ -70,7 +71,7 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file for a GCP workload:`, + Preamble: `Create a credential file for a GCP workload.`, Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/gcp \ @@ -79,7 +80,7 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file for an Azure workload using a User Managed Identity:`, + Preamble: `Create a credential file for an Azure workload using a User Managed Identity.`, Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/azure \ @@ -89,7 +90,7 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file for an Azure workload that has multiple User Managed Identities:`, + Preamble: `Create a credential file for an Azure workload that has multiple User Managed Identities.`, Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/azure \ @@ -100,9 +101,12 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file for an Azure workload that is using a Managed Identity to authenticate as a Entra ID Application:`, + Preamble: heredoc.New(ctx.IO).Must(` + Create a credential file for an Azure workload that is using a Managed Identity to authenticate as a Entra ID Application. Generally, + {{ template "mdCodeOrBold" "ENTRA_ID_APP_ID_URL" }} has the form + {{ template "mdCodeOrBold" "api://123-456-678-901" }}. + `), Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` - # ENTRA_ID_APP_ID_URL generally has the form "api://123-456-678-901" $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/azure \ --azure \ @@ -112,20 +116,28 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file that sources the token from a file:`, + Preamble: heredoc.New(ctx.IO).Must(` + Create a credential file that sources the token from a file. + The following example assumes + {{ template "mdCodeOrBold" "credentials.json" }} has a JSON payload that + contains multiple attributes, including an access token. + `), Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` - # Assuming the file has the following JSON payload: - # { - # "access_token": "eyJ0eXAiOiJKV1Qi...", - # ... - # } $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/k8s \ --source-file=/var/run/secrets/tokens/hcp_token \ --source-json-pointer=/access_token \ --output-file=credentials.json - - # Assuming the file only contains the access token: + `), + }, + { + Preamble: heredoc.New(ctx.IO).Must(` + Create a credential file that sources the token from a file. + The following example assumes + {{ template "mdCodeOrBold" "credentials.json" }} has a JSON payload that + only contains an access token. + `), + Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/k8s \ --source-file \ @@ -133,26 +145,34 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file that sources the token from an URL:`, + Preamble: `Create a credential file that sources the token from an URL. + The following example assumes the URL returns has a JSON payload that + contains multiple attributes, including an access token.`, Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` - # Assuming the response has the following JSON payload: - # { - # "access_token": "eyJ0eXAiOiJKV1Qi...", - # ... - # } $ 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" \ --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. + The following example assumes the URL returns has a JSON payload that + only contains an access token.`, + Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` $ 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 - - # To add headers to the request, use the --source-header flag: + `), + }, + { + Preamble: heredoc.New(ctx.IO).Must(` + Create a credential file that sources the token from an URL. + The following example uses {{ template "mdCodeOrBold" "--source-header" }} + to add a header to the request.`), + Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` $ 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 \ @@ -162,20 +182,20 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file that sources the token from an environment variable:`, + Preamble: `Create a credential file that sources the token from an environment variable. The following example assumes the environment + varible is a JSON payload that contains multiple attributes, including an access token.`, Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` - # Assuming the environment variable has the following JSON string value: - # { - # "access_token": "eyJ0eXAiOiJKV1Qi...", - # ... - # } $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/example \ --source-env=ACCESS_TOKEN \ --source-json-pointer=/access_token \ --output-file=credentials.json - - # Assuming the environment variable only contains the access token: + `), + }, + { + Preamble: `Create a credential file that sources the token from an environment variable. The following example assumes the environment + varible is a JSON payload that only contains an access token.`, + Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/example \ --source-env=ACCESS_TOKEN \ @@ -231,7 +251,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 +276,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,10 +305,10 @@ 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 +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. @@ -300,10 +320,10 @@ 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), }, diff --git a/internal/commands/iam/workloadidentityproviders/create_oidc.go b/internal/commands/iam/workloadidentityproviders/create_oidc.go index 94e27822..e191fd04 100644 --- a/internal/commands/iam/workloadidentityproviders/create_oidc.go +++ b/internal/commands/iam/workloadidentityproviders/create_oidc.go @@ -63,9 +63,9 @@ func NewCmdCreateOIDC(ctx *cmd.Context, runF func(*CreateOIDCOpts) error) *cmd.C `), }, { - Preamble: `GCP - Allow exchanging a Service Account Identity:`, + Preamble: `GCP - Allow exchanging a Service Account Identity + ([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 +74,9 @@ func NewCmdCreateOIDC(ctx *cmd.Context, runF func(*CreateOIDCOpts) error) *cmd.C `), }, { - Preamble: `GitLab - Allow exchanging a GitLab:`, + Preamble: `GitLab - Allow exchanging a GitLab + ([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 +117,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 +131,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." syntax. As an example, access the subject claim with "jwt_claims.sub". + the {{ template "mdCodeOrBold" "jwt_claims." }} syntax. + As an example, access the subject claim with + {{ template "mdCodeOrBold" "jwt_claims.sub" }}. `), Value: flagvalue.Simple("", &opts.ConditionalAccess), Required: true, diff --git a/internal/commands/iam/workloadidentityproviders/list.go b/internal/commands/iam/workloadidentityproviders/list.go index e0e1f9c9..b1bb39f0 100644 --- a/internal/commands/iam/workloadidentityproviders/list.go +++ b/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"), }, }, }, diff --git a/internal/commands/iam/workloadidentityproviders/wips.go b/internal/commands/iam/workloadidentityproviders/wips.go index 6a530751..49124b00 100644 --- a/internal/commands/iam/workloadidentityproviders/wips.go +++ b/internal/commands/iam/workloadidentityproviders/wips.go @@ -28,7 +28,7 @@ func NewCmdWIPs(ctx *cmd.Context) *cmd.Command { ShortHelp: "Manage Workload Identity Providers.", LongHelp: heredoc.New(ctx.IO).Must(` The {{ template "mdCodeOrBold" "hcp iam workload-identity-providers" }} command group - allows you to create and manage Workload Identity Providers. + lets you create and manage Workload Identity Providers. Creating a workload identity provider creates a trust relationship between HCP and an external identity provider. Once created, a workload diff --git a/internal/commands/organizations/iam/add_binding.go b/internal/commands/organizations/iam/add_binding.go index e0303880..7161b0a3 100644 --- a/internal/commands/organizations/iam/add_binding.go +++ b/internal/commands/organizations/iam/add_binding.go @@ -35,7 +35,7 @@ func NewCmdAddBinding(ctx *cmd.Context, runF func(*AddBindingOpts) error) *cmd.C `), Examples: []cmd.Example{ { - Preamble: `Bind a principal to role "roles/viewer":`, + Preamble: heredoc.New(ctx.IO).Must(`Bind a principal to role {{ template "mdCodeOrBold" "roles/viewer" }}:`), Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` $ hcp organizations iam add-binding \ --member=ef938a22-09cf-4be9-b4d0-1f4587f80f53 \ diff --git a/internal/commands/organizations/iam/delete_binding.go b/internal/commands/organizations/iam/delete_binding.go index 5bdc1746..bf489938 100644 --- a/internal/commands/organizations/iam/delete_binding.go +++ b/internal/commands/organizations/iam/delete_binding.go @@ -31,7 +31,7 @@ func NewCmdDeleteBinding(ctx *cmd.Context, runF func(*DeleteBindingOpts) error) `), Examples: []cmd.Example{ { - Preamble: `Delete a role binding for a principal previously granted role "roles/viewer":`, + Preamble: heredoc.New(ctx.IO).Must(`Delete a role binding for a principal previously granted role {{ template "mdCodeOrBold" "roles/viewer" }}:`), Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` $ hcp organizations iam delete-binding \ --member=ef938a22-09cf-4be9-b4d0-1f4587f80f53 \ diff --git a/internal/commands/organizations/list.go b/internal/commands/organizations/list.go index df78c5a2..e72640e1 100644 --- a/internal/commands/organizations/list.go +++ b/internal/commands/organizations/list.go @@ -26,8 +26,8 @@ func NewCmdList(ctx *cmd.Context, runF func(*ListOpts) error) *cmd.Command { Name: "list", ShortHelp: "List organizations.", LongHelp: heredoc.New(ctx.IO).Must(` - "The {{ template "mdCodeOrBold" "hcp organizations list" }} command - lists the organizations the authenticated principal is a member of." + The {{ template "mdCodeOrBold" "hcp organizations list" }} command + lists the organizations the authenticated principal is a member of. `), RunF: func(c *cmd.Command, args []string) error { if runF != nil { diff --git a/internal/commands/profile/profiles/activate.go b/internal/commands/profile/profiles/activate.go index aef91b67..bc22f8b4 100644 --- a/internal/commands/profile/profiles/activate.go +++ b/internal/commands/profile/profiles/activate.go @@ -22,8 +22,10 @@ func NewCmdActivate(ctx *cmd.Context) *cmd.Command { `), Examples: []cmd.Example{ { - Preamble: "To active profile my-profile, run:", - Command: "$ hcp profile profiles activate my-profile", + Preamble: heredoc.New(ctx.IO).Must(` + To active profile {{ template "mdCodeOrBold" "my-profile" }}, run: + `), + Command: "$ hcp profile profiles activate my-profile", }, }, Args: cmd.PositionalArguments{ diff --git a/internal/commands/profile/profiles/rename.go b/internal/commands/profile/profiles/rename.go index 669c9b3a..aa5651de 100644 --- a/internal/commands/profile/profiles/rename.go +++ b/internal/commands/profile/profiles/rename.go @@ -24,8 +24,11 @@ func NewCmdRename(ctx *cmd.Context) *cmd.Command { `), Examples: []cmd.Example{ { - Preamble: "To rename profile my-profile to new-profile, run:", - Command: "$ hcp profile profiles rename my-profile --new-name=new-profile", + Preamble: heredoc.New(ctx.IO).Must(` + To rename profile {{ template "mdCodeOrBold" "my-profile" }} to + {{ template "mdCodeOrBold" "new-profile" }}, run: + `), + Command: "$ hcp profile profiles rename my-profile --new-name=new-profile", }, }, Args: cmd.PositionalArguments{ diff --git a/internal/commands/profile/property_docs.go b/internal/commands/profile/property_docs.go index 7b525652..605138a6 100644 --- a/internal/commands/profile/property_docs.go +++ b/internal/commands/profile/property_docs.go @@ -36,13 +36,13 @@ func addCoreProperties(b *availablePropertiesBuilder) { b.AddProperty("core", "no_color", "If True, color will not be used when printing messages in the terminal.") b.AddProperty("core", "verbosity", ` Default logging verbosity for {{ template "mdCodeOrBold" "hcp" }} commands. This is the - equivalent of using the global --verbosity flag. Supported log levels: + equivalent of using the global {{ template "mdCodeOrBold" "--verbosity" }} flag. Supported log levels: {{ template "mdCodeOrBold" "trace" }}, {{ template "mdCodeOrBold" "debug" }}, {{ template "mdCodeOrBold" "info" }}, {{ template "mdCodeOrBold" "warn" }}, and {{ template "mdCodeOrBold" "error" }}. `) b.AddProperty("core", "output_format", ` Default output format for {{ template "mdCodeOrBold" "hcp" }} commands. This is the - equivalent of using the global --format flag. Supported output foramts: + equivalent of using the global {{ template "mdCodeOrBold" "--format" }} flag. Supported output formats: {{ template "mdCodeOrBold" "pretty" }}, {{ template "mdCodeOrBold" "table" }}, and {{ template "mdCodeOrBold" "json" }}.`) } @@ -144,8 +144,7 @@ func (b availablePropertiesBuilder) buildMD() string { keys := maps.Keys(b.properties[c]) slices.Sort(keys) for _, k := range keys { - fmt.Fprintln(&buf, indent.String(fmt.Sprintf("* `%s`", cs.String(k)), 4)) - fmt.Fprintln(&buf, indent.String(fmt.Sprintf("* %s", b.properties[c][k]), 8)) + fmt.Fprintln(&buf, indent.String(fmt.Sprintf("* `%s` - %s", cs.String(k), b.properties[c][k]), 4)) fmt.Fprintln(&buf) } } diff --git a/internal/commands/projects/create.go b/internal/commands/projects/create.go index 687ad723..2bf71c6e 100644 --- a/internal/commands/projects/create.go +++ b/internal/commands/projects/create.go @@ -35,7 +35,7 @@ func NewCmdCreate(ctx *cmd.Context, runF func(*CreateOpts) error) *cmd.Command { Name: "create", ShortHelp: "Create a new project.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp products create" }} command creates + The {{ template "mdCodeOrBold" "hcp projects create" }} command creates a new project with the given name. The currently authenticated principal will be given role "admin" on the newly created project. `), diff --git a/internal/commands/projects/delete.go b/internal/commands/projects/delete.go index 2e741e18..6ab3193c 100644 --- a/internal/commands/projects/delete.go +++ b/internal/commands/projects/delete.go @@ -25,7 +25,7 @@ func NewCmdDelete(ctx *cmd.Context, runF func(*DeleteOpts) error) *cmd.Command { Name: "delete", ShortHelp: "Delete a project.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp products delete" }} command deletes + The {{ template "mdCodeOrBold" "hcp projects delete" }} command deletes the specified project. The project must be empty before it can be deleted. `), diff --git a/internal/commands/projects/iam/add_binding.go b/internal/commands/projects/iam/add_binding.go index 47b718dd..f119a595 100644 --- a/internal/commands/projects/iam/add_binding.go +++ b/internal/commands/projects/iam/add_binding.go @@ -24,14 +24,15 @@ func NewCmdAddBinding(ctx *cmd.Context, runF func(*AddBindingOpts) error) *cmd.C Name: "add-binding", ShortHelp: "Add an IAM policy binding for a project.", LongHelp: heredoc.New(ctx.IO).Must(` - Add an IAM policy binding for the given project. A binding grants the + The {{ template "mdCodeOrBold" "hcp projects iam add-binding" }} + command adds an IAM policy binding for the given project. A binding grants the specified principal the given role on the project. To view the available roles to bind, run {{ template "mdCodeOrBold" "hcp iam roles list" }}. `), Examples: []cmd.Example{ { - Preamble: `Bind a principal to role "roles/viewer":`, + Preamble: heredoc.New(ctx.IO).Must(`Bind a principal to role {{ template "mdCodeOrBold" "roles/viewer" }}:`), Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` $ hcp projects add-binding \ --project=8647ae06-ca65-467a-b72d-edba1f908fc8 \ diff --git a/internal/commands/projects/iam/delete_binding.go b/internal/commands/projects/iam/delete_binding.go index 4e1d8d69..6aa4cc6d 100644 --- a/internal/commands/projects/iam/delete_binding.go +++ b/internal/commands/projects/iam/delete_binding.go @@ -24,14 +24,15 @@ func NewCmdDeleteBinding(ctx *cmd.Context, runF func(*DeleteBindingOpts) error) Name: "delete-binding", ShortHelp: "Delete an IAM policy binding for a project.", LongHelp: heredoc.New(ctx.IO).Must(` - Deletes an IAM policy binding for the given project. A binding consists of a + The {{ template "mdCodeOrBold" "hcp projects iam delete-binding" }} + command deletes an IAM policy binding for the given project. A binding consists of a principal and a role. To view the existing role bindings, run {{ template "mdCodeOrBold" "hcp projects iam read-policy" }}. `), Examples: []cmd.Example{ { - Preamble: `Delete a role binding for a principal previously granted role "roles/viewer":`, + Preamble: heredoc.New(ctx.IO).Must(`Delete a role binding for a principal previously granted role {{ template "mdCodeOrBold" "roles/viewer" }}:`), Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` $ hcp projects iam delete-binding \ --project=8647ae06-ca65-467a-b72d-edba1f908fc8 \ diff --git a/internal/commands/projects/iam/iam.go b/internal/commands/projects/iam/iam.go index 22184d64..bf8d5118 100644 --- a/internal/commands/projects/iam/iam.go +++ b/internal/commands/projects/iam/iam.go @@ -10,7 +10,7 @@ func NewCmdIAM(ctx *cmd.Context) *cmd.Command { Name: "iam", ShortHelp: "Manage a project's IAM policy.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp projects iam" }} command group is used to + The {{ template "mdCodeOrBold" "hcp projects iam" }} command group lets you manage a project's IAM Policy. `), } diff --git a/internal/commands/projects/iam/read_policy.go b/internal/commands/projects/iam/read_policy.go index 7bce85b7..dd1208a6 100644 --- a/internal/commands/projects/iam/read_policy.go +++ b/internal/commands/projects/iam/read_policy.go @@ -26,7 +26,9 @@ func NewCmdReadPolicy(ctx *cmd.Context, runF func(*ReadPolicyOpts) error) *cmd.C cmd := &cmd.Command{ Name: "read-policy", ShortHelp: "Read the IAM policy for a project.", - LongHelp: "Read the IAM policy for a project.", + LongHelp: heredoc.New(ctx.IO).Must(` + The {{ template "mdCodeOrBold" "hcp projects iam read-policy" }} command reads the IAM policy for a project. + `), Examples: []cmd.Example{ { Preamble: "Read the IAM Policy for a project:", diff --git a/internal/commands/projects/list.go b/internal/commands/projects/list.go index 938b364d..cecba480 100644 --- a/internal/commands/projects/list.go +++ b/internal/commands/projects/list.go @@ -26,7 +26,7 @@ func NewCmdList(ctx *cmd.Context, runF func(*ListOpts) error) *cmd.Command { Name: "list", ShortHelp: "List HCP projects.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp products create" }} command lists HCP projects. + The {{ template "mdCodeOrBold" "hcp projects list" }} command lists HCP projects. `), RunF: func(c *cmd.Command, args []string) error { if runF != nil { diff --git a/internal/commands/projects/read.go b/internal/commands/projects/read.go index 3c728a35..5cccf4bf 100644 --- a/internal/commands/projects/read.go +++ b/internal/commands/projects/read.go @@ -25,7 +25,7 @@ func NewCmdRead(ctx *cmd.Context, runF func(*ReadOpts) error) *cmd.Command { Name: "read", ShortHelp: "Show metadata for the project.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp products read" }} command shows metadata for the project. + The {{ template "mdCodeOrBold" "hcp projects read" }} command shows metadata for the project. `), Examples: []cmd.Example{ { diff --git a/internal/commands/projects/update.go b/internal/commands/projects/update.go index b4340c70..88c2d676 100644 --- a/internal/commands/projects/update.go +++ b/internal/commands/projects/update.go @@ -24,7 +24,7 @@ func NewCmdUpdate(ctx *cmd.Context, runF func(*UpdateOpts) error) *cmd.Command { Name: "update", ShortHelp: "Update an existing project.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp products update" }} command shows metadata for the project. + The {{ template "mdCodeOrBold" "hcp projects update" }} command shows metadata for the project. `), Examples: []cmd.Example{ { diff --git a/internal/commands/waypoint/agent/agent.go b/internal/commands/waypoint/agent/agent.go index 81956506..b35313a8 100644 --- a/internal/commands/waypoint/agent/agent.go +++ b/internal/commands/waypoint/agent/agent.go @@ -10,8 +10,8 @@ func NewCmdAgent(ctx *cmd.Context) *cmd.Command { Name: "agent", ShortHelp: "Run and manage a Waypoint Agent.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp waypoint agent" }} command group allows you to run - and manage a local Waypoint agent. + The {{ template "mdCodeOrBold" "hcp waypoint agent" }} command group lets you + run and manage a local Waypoint agent. Agents are used in conjunction with HCP Waypoint Actions to allow actions to run on your own systems when initiated from HCP Waypoint. diff --git a/internal/commands/waypoint/waypoint.go b/internal/commands/waypoint/waypoint.go index d37af3b8..b68f1f9e 100644 --- a/internal/commands/waypoint/waypoint.go +++ b/internal/commands/waypoint/waypoint.go @@ -13,8 +13,8 @@ func NewCmdWaypoint(ctx *cmd.Context) *cmd.Command { Name: "waypoint", ShortHelp: "Manage Waypoint.", LongHelp: heredoc.New(ctx.IO).Must(` - The {{ template "mdCodeOrBold" "hcp waypoint" }} command group allows users to - manage HCP Waypoint resources through the CLI. These commands allow the user to interact + The {{ template "mdCodeOrBold" "hcp waypoint" }} command group lets you + manage HCP Waypoint resources through the CLI. These commands let you to interact with their HCP Waypoint instance to manage their application deployment process. `), } diff --git a/internal/pkg/cmd/gen_md.go b/internal/pkg/cmd/gen_md.go index 6b33c708..eeaafbc2 100644 --- a/internal/pkg/cmd/gen_md.go +++ b/internal/pkg/cmd/gen_md.go @@ -96,7 +96,7 @@ func GenMarkdown(c *Command, w io.Writer, link LinkHandler) error { if len(c.Aliases) > 0 { buf.WriteString("## Aliases\n\n") for a, u := range c.aliasUsages() { - buf.WriteString(fmt.Sprintf("%s - `%s`\n", a, u)) + buf.WriteString(fmt.Sprintf("- `%s`. For example: `%s`\n", a, u)) } buf.WriteString("\n") } @@ -116,7 +116,7 @@ func GenMarkdown(c *Command, w io.Writer, link LinkHandler) error { var commands, groups []string for _, c := range c.children { path := strings.ReplaceAll(c.commandPath(), " ", "/") - entry := fmt.Sprintf("- [%s](%s) - %s", c.Name, link(path), c.ShortHelp) + entry := fmt.Sprintf("- [`%s`](%s) - %s", c.Name, link(path), c.ShortHelp) if c.RunF != nil { commands = append(commands, entry) @@ -230,7 +230,7 @@ func genMarkdownFlagsetUsage(flags *pflag.FlagSet, buf *bytes.Buffer) { longDisplay := flagString(flag) if flag.Shorthand != "" && flag.ShorthandDeprecated == "" { - fmt.Fprintf(buf, "- `-%s, %s` -", flag.Shorthand, longDisplay) + fmt.Fprintf(buf, "- `-%s, %s` - ", flag.Shorthand, longDisplay) } else { fmt.Fprintf(buf, "- `%s` - ", longDisplay) } From e0c5f59080857683c641795fa2702d0edc5b6419 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Thu, 21 Mar 2024 11:21:38 -0700 Subject: [PATCH 6/8] revert iam to codeblock comments --- .../create_cred_file.go | 70 +++++++++---------- 1 file changed, 33 insertions(+), 37 deletions(-) diff --git a/internal/commands/iam/workloadidentityproviders/create_cred_file.go b/internal/commands/iam/workloadidentityproviders/create_cred_file.go index 9244b388..e2171f2f 100644 --- a/internal/commands/iam/workloadidentityproviders/create_cred_file.go +++ b/internal/commands/iam/workloadidentityproviders/create_cred_file.go @@ -60,10 +60,9 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), Examples: []cmd.Example{ { - Preamble: heredoc.New(ctx.IO).Must(` - Create a credential file for an AWS workload. If the AWS instance metadata service is using version 1, you must set the - {{ template "mdCodeOrBold" "--imdsv1" }} flag.`), + Preamble: `Create a credential file for an AWS workload:`, Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` + # Set the --imdsv1 flag if the AWS instance metadata service is using version 1. $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/aws \ --aws \ @@ -71,7 +70,7 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file for a GCP workload.`, + Preamble: `Create a credential file for a GCP workload:`, Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/gcp \ @@ -80,7 +79,7 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file for an Azure workload using a User Managed Identity.`, + Preamble: `Create a credential file for an Azure workload using a User Managed Identity:`, Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/azure \ @@ -90,7 +89,7 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file for an Azure workload that has multiple User Managed Identities.`, + Preamble: `Create a credential file for an Azure workload that has multiple User Managed Identities:`, Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/azure \ @@ -101,12 +100,9 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: heredoc.New(ctx.IO).Must(` - Create a credential file for an Azure workload that is using a Managed Identity to authenticate as a Entra ID Application. Generally, - {{ template "mdCodeOrBold" "ENTRA_ID_APP_ID_URL" }} has the form - {{ template "mdCodeOrBold" "api://123-456-678-901" }}. - `), + Preamble: `Create a credential file for an Azure workload that is using a Managed Identity to authenticate as a Entra ID Application:`, Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` + # ENTRA_ID_APP_ID_URL generally has the form "api://123-456-678-901" $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/azure \ --azure \ @@ -116,13 +112,13 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: heredoc.New(ctx.IO).Must(` - Create a credential file that sources the token from a file. - The following example assumes - {{ template "mdCodeOrBold" "credentials.json" }} has a JSON payload that - contains multiple attributes, including an access token. - `), + Preamble: `Create a credential file that sources the token from a file.`, Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` + # Assuming the file has the following JSON payload: + # { + # "access_token": "eyJ0eXAiOiJKV1Qi...", + # ... + # } $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/k8s \ --source-file=/var/run/secrets/tokens/hcp_token \ @@ -131,13 +127,9 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: heredoc.New(ctx.IO).Must(` - Create a credential file that sources the token from a file. - The following example assumes - {{ template "mdCodeOrBold" "credentials.json" }} has a JSON payload that - only contains an access token. - `), + 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 \ --source-file \ @@ -145,10 +137,13 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file that sources the token from an URL. - The following example assumes the URL returns has a JSON payload that - contains multiple attributes, including an access token.`, + Preamble: `Create a credential file that sources the token from an URL:`, Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` + # Assuming the response has the following JSON payload: + # { + # "access_token": "eyJ0eXAiOiJKV1Qi...", + # ... + # } $ 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" \ @@ -157,10 +152,9 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file that sources the token from an URL. - The following example assumes the URL returns has a JSON payload that - only contains an 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 \ @@ -168,11 +162,9 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: heredoc.New(ctx.IO).Must(` - Create a credential file that sources the token from an URL. - The following example uses {{ template "mdCodeOrBold" "--source-header" }} - to add a header to the request.`), + 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 \ --source-url=https://example-oidc-provider.com/token \ @@ -182,9 +174,13 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file that sources the token from an environment variable. The following example assumes the environment - varible is a JSON payload that contains multiple attributes, including an access token.`, + 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 has the following JSON string value: + # { + # "access_token": "eyJ0eXAiOiJKV1Qi...", + # ... + # } $ hcp iam workload-identity-providers create-cred-file \ iam/project/123/service-principal/my-sp/workload-identity-provider/example \ --source-env=ACCESS_TOKEN \ @@ -193,9 +189,9 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file that sources the token from an environment variable. The following example assumes the environment - varible is a JSON payload that only contains an access token.`, + 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 \ --source-env=ACCESS_TOKEN \ From 97ce89555d2c16e713e8672d6b3013a98cbe3992 Mon Sep 17 00:00:00 2001 From: Tu Nguyen Date: Thu, 21 Mar 2024 11:22:34 -0700 Subject: [PATCH 7/8] revert iam to codeblock comments --- .../commands/iam/workloadidentityproviders/create_cred_file.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/commands/iam/workloadidentityproviders/create_cred_file.go b/internal/commands/iam/workloadidentityproviders/create_cred_file.go index e2171f2f..24d67b51 100644 --- a/internal/commands/iam/workloadidentityproviders/create_cred_file.go +++ b/internal/commands/iam/workloadidentityproviders/create_cred_file.go @@ -112,7 +112,7 @@ func NewCmdCreateCredFile(ctx *cmd.Context, runF func(*CreateCredFileOpts) error `), }, { - Preamble: `Create a credential file that sources the token from a file.`, + Preamble: `Create a credential file that sources the token from a file:`, Command: heredoc.New(ctx.IO, heredoc.WithPreserveNewlines()).Must(` # Assuming the file has the following JSON payload: # { From 59966160af116973a79684c53786dd568430e141 Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Thu, 21 Mar 2024 15:26:07 -0700 Subject: [PATCH 8/8] Small formatting changes --- .../workloadidentityproviders/create_aws.go | 4 ++-- .../create_cred_file.go | 20 ++++++++++--------- .../workloadidentityproviders/create_oidc.go | 18 +++++++++++------ 3 files changed, 25 insertions(+), 17 deletions(-) diff --git a/internal/commands/iam/workloadidentityproviders/create_aws.go b/internal/commands/iam/workloadidentityproviders/create_aws.go index d1a9a2bd..19526261 100644 --- a/internal/commands/iam/workloadidentityproviders/create_aws.go +++ b/internal/commands/iam/workloadidentityproviders/create_aws.go @@ -41,7 +41,7 @@ func NewCmdCreateAWS(ctx *cmd.Context, runF func(*CreateAWSOpts) error) *cmd.Com {{ PreserveNewLines }} * {{ 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 + * {{ template "mdCodeOrBold" "aws.account_id" }}: The AWS account ID number of the account that owns or contains the calling entity. * {{ template "mdCodeOrBold" "aws.user_id" }}: The unique identifier of the calling entity. {{ PreserveNewLines }} @@ -104,7 +104,7 @@ func NewCmdCreateAWS(ctx *cmd.Context, runF func(*CreateAWSOpts) error) *cmd.Com * {{ 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. - * {{ template "mdCodeOrBold" "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, refer to the diff --git a/internal/commands/iam/workloadidentityproviders/create_cred_file.go b/internal/commands/iam/workloadidentityproviders/create_cred_file.go index 24d67b51..6caf71df 100644 --- a/internal/commands/iam/workloadidentityproviders/create_cred_file.go +++ b/internal/commands/iam/workloadidentityproviders/create_cred_file.go @@ -272,7 +272,7 @@ 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 {{ template "mdCodeOrBold" "https://accounts.google.com" }} + with the issuer URI set to {{ template "mdCodeOrBold" "https://accounts.google.com" }} and the default allowed audiences. `), Value: flagvalue.Simple(false, &opts.GCP), @@ -301,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 {{ 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. +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: @@ -318,8 +319,9 @@ As an example, if the JSON payload containing the credential file is: } {{- end }} {{- CodeBlock "credentials" "json hideClipboard" }} -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" }}. +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), }, diff --git a/internal/commands/iam/workloadidentityproviders/create_oidc.go b/internal/commands/iam/workloadidentityproviders/create_oidc.go index e191fd04..c5156301 100644 --- a/internal/commands/iam/workloadidentityproviders/create_oidc.go +++ b/internal/commands/iam/workloadidentityproviders/create_oidc.go @@ -63,8 +63,11 @@ func NewCmdCreateOIDC(ctx *cmd.Context, runF func(*CreateOIDCOpts) error) *cmd.C `), }, { - Preamble: `GCP - Allow exchanging a Service Account Identity - ([List of claims](https://cloud.google.com/compute/docs/instances/verifying-instance-identity#payload)):`, + 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(` $ hcp iam workload-identity-providers create-oidc gcp-example-service-account \ --service-principal=iam/project/PROJECT/service-principal/example-sp \ @@ -74,8 +77,11 @@ func NewCmdCreateOIDC(ctx *cmd.Context, runF func(*CreateOIDCOpts) error) *cmd.C `), }, { - Preamble: `GitLab - Allow exchanging a GitLab - ([Full list of claims](https://docs.gitlab.com/ee/ci/secrets/id_token_authentication.html#token-payload)):`, + 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(` $ hcp iam workload-identity-providers create-oidc gcp-example-service-account \ --service-principal=iam/project/PROJECT/service-principal/example-sp \ @@ -131,8 +137,8 @@ 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 {{ template "mdCodeOrBold" "jwt_claims." }} syntax. - As an example, access the subject claim with + the {{ template "mdCodeOrBold" "jwt_claims." }} syntax. + As an example, access the subject claim with {{ template "mdCodeOrBold" "jwt_claims.sub" }}. `), Value: flagvalue.Simple("", &opts.ConditionalAccess),