CLI Product Specific Style Guide
While the official CF CLI Style Guide is a more detailed guide, this document is a companion to the official style guide.
The goal of this guide is to provide Contributors of the cf CLI with an quick reference document to promote product consistency.
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.
How Do We Display Color
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
Progress Bars
-
resource name,org name,space name, anduser namein cyan -
Okin green flavor text -
Failin red flavor text -
downapps in thecf appdisplay in red flavor text - warnings, error messages,
TIPin plain text
- add a TIP to indicate which commands to run next and/or a list command that can be retrieved in a subsequent system call in a table and/or key-value display.
- Do not print the environment variable or the labels in the output, especially for the former which might contain sensitive data.
- Examples of these commands:
cf set-env,cf set-label:
- If no resources exists (
0):
Idempotent (Exits with 0 to indicate the app state has not changed.)
Idempotent (Exits with 0 to indicate the app state has not changed.)
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)
...
Not logged in. Use 'cf login' to log in.
FAILED
$ cf bind-route-service domain foo
No org and space targeted. Use 'cf target -o ORG -s SPACE' to target an org and space.
FAILED
$ 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.
wlan-10-81-130-168:dora achau$ ./cf create-org nope --noexisto
Incorrect Usage: unknown flag `noexisto'
NAME:
create-org - Create an org
$ cf create-org no-perms
Creating org no-perms as nope...
You are not authorized to perform the requested action
FAILED
$ ./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:
- identify where in the command the validation failed
- provide a helpful message so that they can fix the issue
- 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% 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
- No space in the output message if only one resource is being created/updated; if the output contains a
TIP, a new line should separateOKand theTIP
$ 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
buildpackandstack):
$ 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,
buildpackis being renamed,stackis being reassigned, and thebuildpackposition 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.
$ ./cf enable-org-isolation abby persistent_isolation_segment
Enabling isolation segment persistent_isolation_segment for org abby as admin...
OK
- 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
--forceflag, giving the user the ability to override the prompt
$ ./cf7 delete-org delete
Really delete the org delete, including its spaces, apps, service instances, routes, private domains and space-scoped service brokers? [yN]: y
Deleting org delete as admin...
OK
$ cf org abby
Getting info for org abby as admin...
name: abby
domains: delfina.cli.fun, private.com
quota: default
spaces: abby
isolation segments:
-
nameis used as a column for the resource - column headers are lower case
- headers are in white text, bolded
- alphabetize the list
- we do not display the
OKmessage - 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
- A few commands (
service-access) allow you to filter a list if you provide flag options. The list that is returned must satisfy ALL given requirements. If not all requirements are met, the command should return an empty list.
- flavour text highlights the resource being retrieved and who the user is
- we display flavor text for output information for
resource,orgname,spacename, anduser - for tables, no color for the table itself. The headers are in white and in bold.
$ 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
- cf orgs