A command-line tool to interact with a Cloud Foundry Diego deployment.
Go Shell
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



cfdot is the CF Diego Operator Toolkit, a CLI tool designed to interact with Diego components.

At present, its commands focus on the Diego BBS API, the main public interface to a Diego deployment.

Current Commands

$ cfdot --help
A command-line tool to interact with a Cloud Foundry Diego deployment

  cfdot [command]

Available Commands:
  actual-lrp-groups            List actual LRP groups
  actual-lrp-groups-for-guid   List actual LRP groups for a process guid
  cancel-task                  Cancel task
  cell                         Show the specified cell presence
  cell-state                   Show the specified cell state
  cell-states                  Show cell states for all cells
  cells                        List registered cell presences
  claim-lock                   Claim Locket lock
  claim-presence               Claim Locket presence
  create-desired-lrp           Create a desired LRP
  create-task                  Create a Task
  delete-desired-lrp           Delete a desired LRP
  delete-task                  Delete a Task
  desired-lrp                  Show the specified desired LRP
  desired-lrp-scheduling-infos List desired LRP scheduling infos
  desired-lrps                 List desired LRPs
  domains                      List domains
  help                         Get help on [command]
  locks                        List Locket locks
  lrp-events                   Subscribe to BBS LRP events
  presences                    List Locket presences
  release-lock                 Release Locket lock
  retire-actual-lrp            Retire actual LRP by index and process guid
  set-domain                   Set domain
  task                         Display task
  task-events                  Subscribe to BBS Task events
  tasks                        List tasks in BBS
  update-desired-lrp           Update a desired LRP

  -h, --help   help for cfdot

Use "cfdot [command] --help" for more information about a command.

Running from a BOSH-deployed VM

cfdot is most useful in the context of a running Diego deployment. If you use the generate-deployment-manifest script in diego-release to generate your Diego manifest, cfdot is already available on the BOSH-deployed Diego VMs. To use it:

bosh ssh <DIEGO_JOB>/<INDEX>

The cfdot pre-start script installs the setup script into /etc/profile.d. This setup script does 3 things:

  • Exports environment variables to target the BBS API in the deployment.
  • Puts the cfdot binary on the PATH.
  • Puts a jq binary on the PATH.

Basic Examples

# count the total number of desired instances
$ cfdot desired-lrp-scheduling-infos | jq '.instances' | jq -s 'add'

# show instance counts by state
$ cfdot actual-lrp-groups | jq '.instance, .evacuating | values' | jq -s -r 'group_by(.state)[] | .[0].state + ": " + (length | tostring)'

Building from Source

cfdot requires the Diego BBS client library. If you have already cloned diego-release, you can run the following commands using that diego-release directory as your GOPATH. Alternatively, run these commands with any other GOPATH and go get will automatically fetch the latest BBS code from diego-release.

# Get cfdot and required dependencies
go get code.cloudfoundry.org/cfdot
cd src/code.cloudfoundry.org/cfdot

# Build for Linux
GOOS=linux go build .

# Build for Mac
GOOS=darwin go build .

# Build for Windows
GOOS=windows go build .

Design Tenets

  • Execution is stateless: configuration is specified either as flags or as environment variables.
  • Conform to UNIX conventions of successful output on stdout and error messages on stderr.
  • For BBS API commands, output is a stream of JSON values, one per line, optimal for processing with jq and suitable for processing with bash and other line-based UNIX utilities.