CLI Product Specific Style Guide

Product Style Guide

The goal of this guide is to provide Contributors with an easy-to-reference document to promote product consistency. This document is meant for Contributors to CLI to reference when creating and updating CLI command output.

Because this document is meant to provide a snapshot of user-facing CLI output, please also reference the main CF CLI Style Guide for more in depth information.

Note:

Where possible, these examples reference refactored CLI commands, which displays the newer CLI style of output.
This is a living document as the CLI team works toward consistency and predictability.

Types of Happy Path Output We Display

Creating a resource

$ ./cf create-org abby3
Creating org abby3 as admin...
OK

Assigning role OrgManager to user admin in org abby3...
OK

TIP: Use 'cf target -o "abby3"' to target new org

Creating a resource (if it is a multi-step process)

$ cf create-buildpack v3-delete13 ~/Downloads/modstatic 1
Creating buildpack v3-delete13 as admin...
OK

Uploading buildpack v3-delete13 as admin...
 12.16 MiB / 12.16 MiB [=======================================================================================================] 100.00% 2s
OK

Processing uploaded buildpack v3-delete13...
OK

Reading a resource

$ ./cf stacks
Getting stacks as admin...

name            description
cflinuxfs2      Cloud Foundry Linux-based filesystem (Ubuntu 14.04)
cflinuxfs3      Cloud Foundry Linux-based filesystem (Ubuntu 18.04)
windows2012R2   windows

Updating a resource

$ cf update-buildpack delete-me -i 1 -s cflinuxfs2
Updating buildpack delete-me with stack cflinuxfs2 as admin...
OK

Deleting a resource

$ cf delete-space delete
Really delete the space delete? [yN]: y
Deleting space delete in org bar as admin...
OK

Types of Sad Path Output We Display (error cases)

Flags that cannot be used together (exit `1`)

$ cf update-buildpack delete-me --assign-stack nope -s stack
Incorrect Usage: The following arguments cannot be used together: -s, --assign-stack
FAILED

Too many arguments are passed (exit `1`)

wlan-10-81-130-168:dora achau$ ./cf create-shared-domain dkjfdk dkjfkdjf dkfjdkjf
Incorrect Usage: unexpected argument "dkjfkdjf"
FAILED

NAME:
   create-shared-domain - Create a domain that can be used by all orgs (admin-only)
...

User is not logged in (exit `1`)

Not logged in. Use 'cf login' to log in.
FAILED

Providing resource that does not exist/not accessible due to permissions (exit `1`)

$ cf org nope
Getting info for org nope as admin...
Organization 'nope' not found.
FAILED

$ cf create-buildpack acceptance17 ~/workspace/cf-acceptance-tests/assets/does_not_exist.zip 1
Incorrect Usage: The specified path '/Users/achau/workspace/cf-acceptance-tests/assets/go_calls_rub.zip' does not exist.

Providing an unknown flag option

wlan-10-81-130-168:dora achau$ ./cf create-org nope --noexisto
Incorrect Usage: unknown flag `noexisto'

NAME:
   create-org - Create an org

Insufficient permissions

$ cf create-org no-perms
Creating org no-perms as nope...
You are not authorized to perform the requested action
FAILED

Required arg is not provided (exit `1`)

$ ./cf7 create-service nope
Incorrect Usage: the required arguments `SERVICE_PLAN` and `SERVICE_INSTANCE` were not provided

NAME:
   create-service - Create a service instance
...

cf add-network-policy abby1 --destination-app nono -o new
Incorrect Usage: A space must be provided when an org is provided, but the '-s' flag was not specified.

Providing invalid values for flag options (exit `1`). There are many different responses for this error.

it's preferable to return the exact error message that we get from CAPI so that we don't need to wrap the error message with a custom CLI message. If the error we get back from CAPI is not helpful for some reason, we should talk to CAPI about improving their error message.
if the CLI is required to wrap the error message for some reason, then ensure you detail the exact error:
1. identify where in the command the validation failed
2. provide a helpful message so that they can fix the issue

##TIPS - Add a TIP - this is usually reserved for calling out other commands that will help them understand their error, or if there is additional actions they need to take, for example, restaging their app. - for TIP, if we specify a command for them to run, the command should be in single quotes. The resource they are attempting to update should also be in blue and single quotes.

$ cf create-buildpack v3-delete12 ~/Downloads/modstatic 1
Creating buildpack v3-delete12 as admin...
OK

Uploading buildpack v3-delete12 as admin...
 12.16 MiB / 12.16 MiB [========================================================================================================] 100.00% 1s
OK

Processing uploaded buildpack v3-delete12...
OK
wlan-10-81-130-246:dora achau$ ./cf7 create-buildpack v3-delete12 ~/Downloads/modstatic 1
Creating buildpack v3-delete12 as admin...
OK

Uploading buildpack v3-delete12 as admin...
 12.16 MiB / 12.16 MiB [========================================================================================================] 100.00% 2s
OK

Processing uploaded buildpack v3-delete12...

The buildpack name v3-delete12 is already in use for the stack cflinuxfs2

TIP: Buildpack  'v3-delete12' with a nil stack has been created. Use 'delete-buildpack' or 'cf update-buildpack' to delete or modify the buildpack.

FAILED

How We Display New Lines

No space in the output message if only one resource is being created/updated; if the output contains a TIP, a new line should separate OK and the TIP

$ cf create-user bar user
Creating user bar...
OK

TIP: Assign roles with 'cf set-org-role' and 'cf set-space-role'.

If multiple resources are being created/updated (in this example buildpack and stack):

$ cf update-buildpack abby-delete-delete --assign-stack windows2012R2 -i 1
Assigning stack windows2012R2 to abby-delete-delete as admin...

Updating buildpack abby-delete-delete with stack windows2012R2 as admin...
OK

If multiple resources are being created/updated AND multiple operations are invoked (in this example, buildpack is being renamed, stack is being reassigned, and the buildpack position is updated:

$ ./cf update-buildpack old_buildpack -p ~/Downloads/modstatic --rename new_buildpack --assign-stack cflinuxfs2 -i 5`
Renaming buildpack old_buildpack to new_buildpack in org bar / space dodo as admin...

Assigning stack cflinuxfs2 to new_buildpack as admin...

Updating buildpack new_buildpack with stack cflinuxfs2 as admin...
OK

Display newline between flavor text and tip, flavor text and table
Do not display newline between flavor text and error.

How Do We Display Enabling a Resource

$ ./cf enable-org-isolation abby persistent_isolation_segment
Enabling isolation segment persistent_isolation_segment for org abby as admin...
OK

Prompts

Display them if a command will incur app downtime or if running the command is destructive (deletes more than one resource (examples include delete-org)
Commands which display a prompt can and do include a --force flag, giving the user the ability to override the prompt

$ cf scale nora -k 256m

This will cause the app to restart. Are you sure you want to scale nora?>

$ cf delete-org org1
Really delete the org org1, including its spaces, apps, service instances, routes, private domains and space-scoped service brokers? [yN]: y
Deleting org org1 as admin...
OK

How We Display Details About a Specific Resource (Table and Key Value)

This can be displayed as a key value:

$ cf org abby
Getting info for org abby as admin...

name:                 abby
domains:              delfina.cli.fun, private.com
quota:                default
spaces:               abby
isolation segments:

This can also be displayed as a table:

name is used as a column for the resource
we do not display the OK message
if this is a minor or point release, do not add a new column in the middle of a table; it must be added as the last column in the sequence

$ ./cf stack cflinuxfs2
Getting info for stack cflinuxfs2 as admin...

name:          cflinuxfs2
description:   Cloud Foundry Linux-based filesystem

Flavor Text

flavour text highlights the resource being retrieved and who the user is
we display flavor text for output information for resource, org name, space name, and user
for tables, no color for the table itself. The headers are in white and in bold.

Progress Bars

$ cf create-buildpack abby ~/Downloads/modstatic.zip  1
Creating buildpack abby as admin...
OK

Uploading buildpack abby as admin...
 170 B / 170 B [==============================================================================================================================================================================================================================================================================================================================================] 100.00% 1s

Done uploading
OK

Commands that allow you to retrieve a list when you are not targeted

cf orgs

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLI Product Specific Style Guide

Product Style Guide

Table of Contents

Types of Happy Path Output We Display

Creating a resource

Creating a resource (if it is a multi-step process)

Reading a resource

Updating a resource

Deleting a resource

Types of Sad Path Output We Display (error cases)

Flags that cannot be used together (exit `1`)

Too many arguments are passed (exit `1`)

User is not logged in (exit `1`)

Providing resource that does not exist/not accessible due to permissions (exit `1`)

Providing an unknown flag option

Insufficient permissions

Required arg is not provided (exit `1`)

Providing invalid values for flag options (exit `1`). There are many different responses for this error.

How We Display New Lines

How Do We Display Enabling a Resource

Prompts

How We Display Details About a Specific Resource (Table and Key Value)

This can be displayed as a key value:

This can also be displayed as a table:

Flavor Text

Progress Bars

Commands that allow you to retrieve a list when you are not targeted

Clone this wiki locally

CLI Product Specific Style Guide

Product Style Guide

Table of Contents

Types of Happy Path Output We Display

Creating a resource

Creating a resource (if it is a multi-step process)

Reading a resource

Updating a resource

Deleting a resource

Types of Sad Path Output We Display (error cases)

Flags that cannot be used together (exit 1)

Too many arguments are passed (exit 1)

User is not logged in (exit 1)

Providing resource that does not exist/not accessible due to permissions (exit 1)

Providing an unknown flag option

Insufficient permissions

Required arg is not provided (exit 1)

Providing invalid values for flag options (exit 1). There are many different responses for this error.

How We Display New Lines

How Do We Display Enabling a Resource

Prompts

How We Display Details About a Specific Resource (Table and Key Value)

This can be displayed as a key value:

This can also be displayed as a table:

Flavor Text

Progress Bars

Commands that allow you to retrieve a list when you are not targeted

Clone this wiki locally

Flags that cannot be used together (exit `1`)

Too many arguments are passed (exit `1`)

User is not logged in (exit `1`)

Providing resource that does not exist/not accessible due to permissions (exit `1`)

Required arg is not provided (exit `1`)

Providing invalid values for flag options (exit `1`). There are many different responses for this error.