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 document is a work in progress as we work to move toward consistency and predictability.

Table of Contents

Types of Happy Path Output We Display
Types of Sad Path Output We Display (error cases
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 Display
Favor Text

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

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.

1. 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.
2. 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
   3. 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. See the flavor text section below for display information.

$ ./cf create-buildpack acceptance100 https://github.com/cloudfoundry/staticfile-buildpack/releases/download/v1.4.29/staticfile-buildpack-v1.4.29.zip 0 --enable
Creating buildpack acceptance100 as admin...

Buildpack acceptance100 already exists without a stack.

TIP: Use 'cf buildpacks' and 'cf delete-buildpack' to delete buildpack acceptance100 without a stack.

$ cf create-service overview-service simple no-permsmy-instance-noper -c valid.json -t "{no,error}"

Invalid configuration provided for -c flag. Please provide a valid JSON object or path to a file containing a valid JSON object.
FAILED

How We Display New Lines

• No space in the output message if one operation is being executed
• 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?>

Abbys-MBP-2:dora achau$ ./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.
• for TIP, if we specify a command for them to run, the command should be blue. The resource they are attempting to update should also be in blue. (see the TIP for cf create-buildpack without specifying a stack name)

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

• cf orgs