

Commands

Note

Applies to CLI v3.0.1+.

Installation of the BOSH CLI is required as a prerequisite, see Installing the CLI. Release notes can be found on Github.

Global BOSH CLI Application options¶

These options are available to every command execution:

-v, --version Show CLI version
--config=PATH Config file path (default: ~/.bosh/config) [$BOSH_CONFIG]
-e, --environment=NAME Director environment name or URL [$BOSH_ENVIRONMENT]
--ca-cert=PATH Director CA certificate path or value [$BOSH_CA_CERT]
--sha2 Use SHA256 checksums [$BOSH_SHA2]
--parallel=NUMBER The max number of parallel operations (default: 5)
--client=NAME Override username or UAA client [$BOSH_CLIENT]
--client-secret=SECRET Override password or UAA client secret [$BOSH_CLIENT_SECRET]
-d, --deployment=NAME Deployment name [$BOSH_DEPLOYMENT]
--column=NAME Filter to show only given column(s)
--json Output as JSON
--tty Force TTY-like output
--no-color Toggle colorized output
-n, --non-interactive Don't ask for user input [$BOSH_NON_INTERACTIVE]
-h, --help Show help message

Environments¶

See Environments.

Environments¶

bosh [GLOBAL-CLI-OPTIONS] environments (Alias: envs)

Lists aliased environments known to the CLI. Aliasing is done via alias-env command.
```
bosh envs
```
Should result in:
```
URL              Alias
104.154.171.255  gcp
192.168.56.6     vbox

2 environments

Succeeded
```

Create-Env¶

bosh [GLOBAL-CLI-OPTIONS] create-env [-v ...] [--var-file=PATH] [-l ...] [--vars-env=PREFIX] [--vars-store=PATH] [-o ...] [--skip-drain] [--state=PATH] [--recreate] [--recreate-persistent-disks] PATH

Creates single VM based on the manifest. Typically used to create a Director environment. Operation files and variables can be provided to adjust and fill in manifest before doing a deploy.
- -v, --var=VAR=VALUE Set variable
- --var-file=VAR=PATH Set variable to file contents
- -l, --vars-file=PATH Load variables from a YAML file
- --vars-env=PREFIX Load variables from environment variables (e.g.: 'MY' to load MY_var=value)
- --vars-store=PATH Load/save variables from/to a YAML file
- -o, --ops-file=PATH Load manifest operations from a YAML file
- --skip-drain Skip running drain and pre-stop scripts
- --state=PATH State file path
- --recreate Recreate VM in deployment
- --recreate-persistent-disks Recreate persistent disks in the deployment
- PATH Path to a manifest file
create-env command replaces bosh-init deploy CLI command.
```
bosh create-env ~/workspace/bosh-deployment/bosh.yml \
  --state state.json \
  --vars-store ./creds.yml \
  -o ~/workspace/bosh-deployment/virtualbox/cpi.yml \
  -o ~/workspace/bosh-deployment/virtualbox/outbound-network.yml \
  -o ~/workspace/bosh-deployment/bosh-lite.yml \
  -o ~/workspace/bosh-deployment/jumpbox-user.yml \
  -v director_name=vbox \
  -v internal_ip=192.168.56.6 \
  -v internal_gw=192.168.56.1 \
  -v internal_cidr=192.168.56.0/24 \
  -v network_name=vboxnet0 \
  -v outbound_network_name=NatNetwork
```

Alias-Env¶

bosh [GLOBAL-CLI-OPTIONS] alias-env name -e location

Assigns a name to the created environment for easier access in subsequent CLI commands. Instead of specifying Director location and possibly a CA certificate, subsequent commands can just take given name via --environment flag (-e).
```
bosh alias-env gcp -e bosh.corp.com
bosh alias-env gcp -e 10.0.0.6 --ca-cert <(bosh int creds.yml --path /director_ssl/ca)
```

Unalias-Env¶

bosh [GLOBAL-CLI-OPTIONS] unalias-env ALIAS

Remove an aliased environment. You can get list of aliases from bosh envs
```
bosh unalias-env vbox
```

Delete-Env¶

bosh [GLOBAL-CLI-OPTIONS] delete-env [-v ...] [--var-file=PATH] [-l ...] [--vars-env=PREFIX] [--vars-store=PATH] [-o ...] [--skip-drain] [--state=PATH] PATH

Deletes previously created VM based on the manifest. Same flags provided to create-env command should be given to the delete-env command.
- -v, --var=VAR=VALUE Set variable
- --var-file=VAR=PATH Set variable to file contents
- -l, --vars-file=PATH Load variables from a YAML file
- --vars-env=PREFIX Load variables from environment variables (e.g.: 'MY' to load MY_var=value)
- --vars-store=PATH Load/save variables from/to a YAML file
- -o, --ops-file=PATH Load manifest operations from a YAML file
- --skip-drain Skip running drain and pre-stop scripts
- --state=PATH State file path
- PATH Path to a manifest file
delete-env command replaces bosh-init delete CLI command.
```
bosh delete-env ~/workspace/bosh-deployment/bosh.yml \
  --state state.json \
  --vars-store ./creds.yml \
  -o ~/workspace/bosh-deployment/virtualbox/cpi.yml \
  -o ~/workspace/bosh-deployment/virtualbox/outbound-network.yml \
  -o ~/workspace/bosh-deployment/bosh-lite.yml \
  -o ~/workspace/bosh-deployment/jumpbox-user.yml \
  -v director_name=vbox \
  -v internal_ip=192.168.56.6 \
  -v internal_gw=192.168.56.1 \
  -v internal_cidr=192.168.56.0/24 \
  -v network_name=vboxnet0 \
  -v outbound_network_name=NatNetwork
```

Session¶

Log-In¶

bosh [GLOBAL-CLI-OPTIONS] log-in (Alias: l, login)

Logs in given user into the Director.

This command can only be used interactively. If non-interactive use is necessary (for example in scripts) please set BOSH_CLIENT and BOSH_CLIENT_SECRET environment variables instead of using this command.
```
bosh -e my-env l
# User (): admin
# Password ():
```
Warning

For UAA users, the flags --client, --client-secret and the environment variables BOSH_CLIENT and BOSH_CLIENT_SECRET are not supported, and will not be forwarded to UAA. The only supported login flow for UAA is by using an interactive login. Alternatively UAA users can use UAA clients to login.

Log-Out¶

bosh [GLOBAL-CLI-OPTIONS] log-out (Alias: logout)

Logs out currently logged in user.

Director Environment¶

Environment¶

bosh [GLOBAL-CLI-OPTIONS] environment [--details] (Alias: env)

Shows Director information in the deployment environment.

--details Show director's certificates details

bosh -e vbox env --details

Should result in:

Using environment '192.168.56.6' as '?'

Name      vbox
UUID      eeb27cc6-467e-4c1d-a8f9-f1a8de759f52
Version   260.5.0 (00000000)
CPI       warden_cpi
Features  dns: disabled
          snapshots: disabled
User      admin


CERTIFICATE EXPIRY DATE INFORMATION

Certificate                     Expiry Date (UTC)     Days Left
director.ssl.cert               2018-12-04T21:43:57Z  0
blobstore.tls.cert.ca           2019-11-21T21:44:03Z  352
nats.tls.ca                     2019-11-21T21:43:58Z  352
nats.tls.client_ca.certificate  2018-12-21T21:43:58Z  17
nats.tls.director.certificate   2018-11-21T21:43:59Z  -13

Succeeded

The Days left column is has a visual shortcut that lists certificates with less than 30 full days of validity in red, and all others in green.

Stemcells¶

See Uploading Stemcells.

Stemcells¶

bosh [GLOBAL-CLI-OPTIONS] stemcells (Alias: ss)

Lists stemcells previously uploaded into the Director. Shows their names, versions and CIDs.

bosh -e my-env ss

Should result in:

Using environment '192.168.56.6' as '?'

Name                                         Version    OS             CPI  CID
bosh-warden-boshlite-ubuntu-xenial-go_agent  621.74*    ubuntu-xenial  -    6cbb176a-6a43-42...
~                                            456.112    ubuntu-xenial  -    43r3496a-4rt3-52...
bosh-warden-boshlite-centos-7-go_agent       3363*      centos-7       -    38yr83gg-349r-94...

(*) Currently deployed

3 stemcells

Succeeded

Upload-Stemcell¶

bosh [GLOBAL-CLI-OPTIONS] upload-stemcell [--fix] [--name=NAME] [--version=VERSION] [--sha1=DIGEST] URL (Alias: us)

Uploads stemcell to the Director. Succeeds even if stemcell is already imported.

Stemcell location may be local file system path or an HTTP/HTTPS URL.
- --fix replace previously uploaded stemcell with the same name and version to repair stemcells that might have been corrupted in the cloud.
- --name=NAME Name used in existence check (is not used with local stemcell file)
- --version=VERSION Version used in existence check (is not used with local stemcell file)
- --sha1=DIGEST SHA1 of the remote stemcell (is not used with local files)
- URL Path to a local file or URL
```
bosh -e my-env us ~/Downloads/bosh-stemcell-621.74-warden-boshlite-ubuntu-xenial-go_agent.tgz
bosh -e my-env us https://bosh.io/d/stemcells/bosh-warden-boshlite-ubuntu-xenial-go_agent?v=621.74
```

Delete-Stemcell¶

bosh [GLOBAL-CLI-OPTIONS] delete-stemcell [GLOBAL-CLI-OPTIONS] [--force] NAME/VERSION

Deletes uploaded stemcell from the Director. Succeeds even if stemcell is not found.
- --force Ignore errors
```
bosh -e my-env delete-stemcell bosh-warden-boshlite-ubuntu-xenial-go_agent/621.74
```

Repack-Stemcell¶

bosh [GLOBAL-CLI-OPTIONS] repack-stemcell [--name=NAME] [--cloud-properties=JSON-STRING] [--empty-image] [--format=FORMAT] [--version=VERSION] PATH-TO-STEMCELL PATH-TO-RESULT

Warning

Starting in version CLI v5.4.0, repacking a stemcell will preserve a new field api_version in the manifest. Repacking any stemcells with api_version in their manifest with CLI v5.3.1 and lower will omit the field.

Produces new stemcell tarball with updated properties such as name, version, and cloud properties.
- --name=NAME Repacked stemcell name
- --cloud-properties=JSON-STRING Repacked stemcell cloud properties
- --empty-image Pack zero byte file instead of image
- --format=FORMAT Repacked stemcell formats. Can be used multiple times. Overrides existing formats.
- --version=VERSION Repacked stemcell version
- PATH-TO-STEMCELL Path to stemcell
- PATH-TO-RESULT Path to repacked stemcell
See Repacking stemcells for details.

Inspect-Local-Stemcell¶

bosh [GLOBAL-CLI-OPTIONS] inspect-local-stemcell PATH-TO-STEMCELL

Display information from stemcell metadata.
```
bosh inspect-local-stemcell /path/to/bosh-stemcell-170.5-aws-xen-hvm-ubuntu-xenial-go_agent.tgz
```

Release creation¶

Init-Release¶

bosh [GLOBAL-CLI-OPTIONS] init-release [--dir=DIR] [--git]

Creates an empty release skeleton for a release in dir. By default dir is the current directory.
- --dir=DIR Release directory path if not current working directory (default: .)
- --git initialize release skeleton as a Git repository, adding appropriate .gitignore file.
```
bosh init-release --git --dir release-dir
cd release-dir
```

Generate-Job¶

bosh [GLOBAL-CLI-OPTIONS] generate-job [--dir=DIR] NAME

Creates an empty job skeleton for a release in dir. Includes bare spec and an empty monit file.
- --dir=DIR Release directory path if not current working directory (default: .)

Generate-Package¶

bosh [GLOBAL-CLI-OPTIONS] generate-package [--dir=DIR] NAME

Creates an empty package skeleton for a release in dir. Includes bare spec and an empty packaging file.
- --dir=DIR Release directory path if not current working directory (default: .)

Vendor-Package¶

bosh [GLOBAL-CLI-OPTIONS] vendor-package [--dir=DIR] PACKAGE SRC-DIR (v2.0.36+)

Vendors a package from a different release into a release in dir. It includes spec.lock in the package directory so that CLI will reference specific package by its fingerprint when creating releases.
- --dir=DIR Release directory path if not current working directory (default: .)
- --prefix= Prefix to add to the package name
See Package vendoring for details.

Create-Release¶

bosh [GLOBAL-CLI-OPTIONS] create-release [--dir=DIR] [--name=NAME] [--version=VERSION] [--timestamp-version] [--final] [--tarball=PATH] [--force] [PATH] (Alias: cr)

Creates new version of a release stored in dir
- --dir=DIR Release directory path if not current working directory (default: .)
- --name=NAME Custom release name
- --version=VERSION set release version
- --timestamp-version produce timestamp-based dev release version
- --final Make it a final release
- --tarball=PATH specify destination of a release tarball; if not specified, release tarball will not be produced
- --force include uncommitted changes in the release directory; it should only be used when building dev releases
- PATH path to release yml file
While iterating on a release it's common to run bosh create-release --force && bosh -e my-env upload-release && bosh -e my-env -d my-dep deploy manifest.yml command sequence.

In a CI pipeline it's common to use this command to create a release tarball and pass it into acceptance or end-to-end tests. Once release tarball goes through appropriate tests it can be finalized with a finalize-release command and shared with release consumers.
```
cd release-dir
bosh create-release --force
bosh create-release --timestamp-version
bosh create-release --version 9+dev.10
bosh create-release --tarball /tmp/my-release.tgz
bosh create-release --final
bosh create-release --version 20 --final
bosh create-release releases/zookeeper/zookeeper-3.yml --tarball /tmp/my-release.tgz
```

Finalize-Release¶

bosh [GLOBAL-CLI-OPTIONS] finalize-release [--dir=DIR] [--name=NAME] [--version=VERSION] [--force] PATH

Records contents of a release tarball in the release repository as a final release with an optionally given version. Once .final_builds and releases directories are updated, it's strongly recommended to commit your changes to version control.

Typically this command is used as a final step in the CI pipeline to save the final artifact once it passed appropriate tests.
- --dir=DIR Release directory path if not current working directory (default: .)
- --name=NAME Custom release name
- --version=VERSION Custom release version (e.g.: 1.0.0, 1.0-beta.2+dev.10)
- --force Ignore Git dirty state check
```
cd release-dir
bosh finalize-release /tmp/my-release.tgz
bosh finalize-release /tmp/my-release.tgz --version 20
git commit -am 'Final release 20'
git push origin master
```
- Note: finalize-release does not change the input tarball in any way (i.e. if a --version flag is passed, it will not modify the version present in the tarball itself).

Reset-Release¶

bosh [GLOBAL-CLI-OPTIONS] reset-release [--dir=DIR]

Removes temporary artifacts such as dev releases, blobs, etc. kept in the release directory dir.
- --dir=DIR Release directory path if not current working directory (default: .)

Release blobs¶

See Release Blobs for a detailed workflow.

Blobs¶

bosh [GLOBAL-CLI-OPTIONS] blobs [--dir=DIR]

Lists tracked blobs from config/blobs.yml. Shows uploaded and not-yet-uploaded blobs.

--dir=DIR Release directory path if not current working directory (default: .)

cd release-dir
bosh blobs

Should result in:

Path                               Size     Blobstore ID         Digest
golang/go1.6.2.linux-amd64.tar.gz  81 MiB   f1833f76-ad8b-4b...  b8318b0...
stress/stress-1.0.4.tar.gz         187 KiB  (local)              e1533bc...

2 blobs

Succeeded

Add-Blob¶

bosh [GLOBAL-CLI-OPTIONS] add-blob [--dir=DIR] PATH BLOBS-PATH

Starts tracking blob in config/blobs.yml for inclusion in packages.
- --dir=DIR Release directory path if not current working directory (default: .)
```
cd release-dir
bosh add-blob ~/Downloads/stress-1.0.4.tar.gz stress/stress-1.0.4.tar.gz
```

Remove-Blob¶

bosh [GLOBAL-CLI-OPTIONS] remove-blob [--dir=DIR] BLOBS-PATH

Stops tracking blob in config/blobs.yml. Does not remove previously uploaded copies from the blobstore as older release versions may still want to reference it.
- --dir=DIR Release directory path if not current working directory (default: .)
```
cd release-dir
bosh remove-blob stress/stress-1.0.4.tar.gz
```

Upload-Blobs¶

bosh [GLOBAL-CLI-OPTIONS] upload-blobs [--dir=DIR]

Uploads previously added blobs that were not yet uploaded to the blobstore. Updates config/blobs.yml with returned blobstore IDs. Before creating a final release it's strongly recommended to upload blobs so that other release contributors can rebuild a release from scratch.
- --dir=DIR Release directory path if not current working directory (default: .)
```
cd release-dir
bosh upload-blobs
```

Sync-Blobs¶

bosh sync-blobs [--dir=DIR]

Downloads blobs into blobs/ based on config/blobs.yml.
- --dir=DIR Release directory path if not current working directory (default: .)
```
cd release-dir
bosh sync-blobs
```

Releases¶

See Uploading Releases.

Releases¶

bosh [GLOBAL-CLI-OPTIONS] releases (Alias: rs)

Lists releases previously uploaded into the Director. Shows their names and versions.

bosh -e my-env rs

Should result in:

Using environment '192.168.56.6' as client 'admin'

Name               Version   Commit Hash
capi               1.21.0*   716aa812
cf-mysql           34*       e0508b5
cf-smoke-tests     11*       a6dad6e
cflinuxfs2-rootfs  1.52.0*   4827ef51+
consul             155*      22515a98+
diego              1.8.1*    0cca668e
dns                3*        57e27da
etcd               94*       57c81e16
garden-runc        1.2.0*    2b3dedc5
loggregator        78*       773a3ba
nats               15*       d4dfc4c1+
routing            0.145.0*  dfb44c41+
statsd-injector    1.0.20*   552926d
syslog             9         ac2172f
uaa                25*       86ec7568

(*) Currently deployed
(+) Uncommitted changes

15 releases

Succeeded

Upload-Release¶

bosh [GLOBAL-CLI-OPTIONS] upload-release [--dir=DIR] [--rebase] [--fix] [--name=NAME] [--version=VERSION] [--sha1=DIGEST] [--stemcell=OS/VERSION] [URL] (Alias: ur)

Uploads release to the Director. Succeeds even if release is already imported.

Release location may be local file system path, HTTP/HTTPS URL or a Git URL. See Release URLs for more details.
- --dir=DIR Release directory path if not current working directory (default: .)
- --rebase Rebases this release onto the latest version known by the Director
- --fix Replaces corrupt and missing jobs and packages
- --name=NAME Name used in existence check (is not used with local release file)
- --version=VERSION Version used in existence check (is not used with local release file)
- --sha1=DIGEST SHA1 of the remote release (is not used with local files)
- --stemcell=OS/VERSION Stemcell that the release is compiled against (applies to remote releases)
- URL Path to a local file or URL
```
bosh -e my-env ur
bosh -e my-env ur https://bosh.io/d/github.com/concourse/concourse?v=2.7.3
bosh -e my-env ur git+https://github.com/concourse/concourse --version 2.7.3
```

Delete-Release¶

bosh [GLOBAL-CLI-OPTIONS] delete-release [--force] NAME[/VERSION]

Deletes uploaded release from the Director. Succeeds even if release is not found.
- --force Ignore errors
```
bosh -e my-env delete-release cf-smoke-tests/94
```

Export-Release¶

bosh [GLOBAL-CLI-OPTIONS] export-release [--dir=DIR] [--job=NAME] NAME/VERSION OS/VERSION

Compiles and exports a release against a particular stemcell version.

Requires to operate with a deployment so that compilation resources (VMs) are properly tracked.
- --dir=DIR Destination directory (default: .)
- --job=NAME Name of job to export
```
bosh -e my-env -d my-dep export-release cf-smoke-tests/94 ubuntu-xenial/621.74
```

Inspect-Release¶

bosh [GLOBAL-CLI-OPTIONS] inspect-release NAME/VERSION

Lists all jobs, job metadata (such as links), packages, and compiled packages associated with a release version.

bosh -e gcp-test inspect-release consul/155

Should result in:

Using environment '192.168.56.6' as client 'admin'

Job                                                                    Blobstore ID       Digest       Links Consumed    Links Provided
acceptance-tests/943c6083581e623dc66c7d9126d8e5989c4c2b31              0f3cd013-1d3d-...  17e5e4fc...  -                 -
consul-test-consumer-windows/6748c0675da2292c680da03e89b738a9d5818370  7461c74c-745d-...  9809861c...  -                 -
consul-test-consumer/7263db87ba85eaf0dd41bd198359c8597e961839          8bde4572-8e8b-...  7b08b059...  -                 -
consul_agent/b4872109282347700eaa884dcfe93f3a03dc22dd                  e41f705e-2cb7-...  a8db2c76...  - name: consul    - name: consul
                                                                                                         type: consul      type: consul
                                                                                                         optional: true
consul_agent_windows/a0b91cb0aa1029734d77fcf064dafdb67f14ada6          3a8755d0-7a39-...  17f07ec0...  - name: consul    - name: consul
                                                                                                         type: consul      type: consul
                                                                                                         optional: true
fake-dns-server/a1ea5f64de0860512470ace7ce2376aa9470f9b1               5bb53f17-eba9-...  0565f9af...  -                 -

6 jobs

Package                                                            Compiled for          Blobstore ID            Digest
acceptance-tests-windows/e36cef763e5cfd4e28738ad314807e6d1e13b960  (source)              03589024-2596-49fc-...  96eaaf4ba...
acceptance-tests/9d56ac03d7410dcdfd96a8c96bbc79eb4b53c864          (source)              79fb9ba7-cd23-4b93-...  e08ee88f5...
confab-windows/52b117effcd95138eca94c789530bcd6499cff9d            (source)              53d4b206-b064-462d-...  43f92c8d0...
confab/b2ff0bbd68b7d600ecb1ffaf41f59af073e894fd                    (source)              b93214eb-a816-4029-...  4b627d264...
~                                                                  ubuntu-xenial/621.74  f66fe541-8c21-4fe3-...  8e662c2e2...
consul-windows/2a8e0b7ce1424d1d5efe5c7184791481a0c26424            (source)              9516870b-801e-42ea-...  19db18127...
consul/6049d3016cd34ac64ccbf7837b06b6db81942102                    (source)              04aa38af-e883-4842-...  c42cacfc7...
~                                                                  ubuntu-xenial/621.74  ab4afda6-881e-46b1-...  27c1390fa...
golang1.7-windows/1a80382e081cd429cf518f0c783f4e4172cac79e         (source)              d7670210-7038-4749-...  b91caa06a...
golang1.7/181f7537c2ec17ac2406d9f2eb3322fd80fa2a1c                 (source)              ac8aa36a-8965-46e9-...  ca440d716...
~                                                                  ubuntu-xenial/621.74  9d40794f-0c50-4d0c-...  9d6e29221...

11 packages

Succeeded

Inspect-Local-Release¶

bosh [GLOBAL-CLI-OPTIONS] inspect-local-release PATH

Lists all jobs, packages, and compiled packages associated with a release tarball.

bosh inspect-local-release bpm-1.0.3-ubuntu-xenial-250.25-20190327-162856-776883319.tgz

Should result in:

Name         bpm
Version      1.0.3
Commit Hash  d2f7197
Archive      bpm-1.0.3-ubuntu-xenial-250.25-20190327-162856-776883319.tgz

Job                                                   Digest                                    Packages
bpm/fafbd62c034aaf20947ec9c9e7102959ca73db8c          1d17ace7f7cef72554b5fe3106212dd43ed76953  -
test-errand/1ccf9ec7a47043218a7d080a5d674077bfc28529  ff901be8452289d0590a36eb7823174ae8104c7f  -
test-server/80db4f3e3ef3ce7301c5a256357dd158df147a70  bee2983cffc928354cc2a48f929ed1c4d42ce59d  -

3 jobs

Package                                               Digest                                    Dependencies  OS             OS Version
bpm-runc/b1010b27bec38acce027b2d1d8a1c10b71bb6f87     2046ffbd400ddf71fd6a01114a37714e0d531ea5  golang        ubuntu-xenial  250.25
bpm/0c350861f27a4b912fb578bfa88d97d1dafe1602          a9dfddb259c4674138da48b9a538aef6b18ab274  golang        ubuntu-xenial  250.25
bpm-runc
golang/4f7fa7648892d4d98b7912c945638c8f32f52d6f       2d1b33e23642b159cf012e83597a7ab63933eaa5  -             ubuntu-xenial  250.25
test-server/b748494d5c1031c9943e0d7f3982e4b09fce36f5  612a488cf46a32883bee4f0415fdcf83de9ee5ec  golang        ubuntu-xenial  250.25

4 packages

Succeeded

Configs¶

See Configs.

Configs¶

bosh [GLOBAL-CLI-OPTIONS] configs [--name=NAME] [--type=TYPE] [-r ...]

Lists all the configs on the Director.
- --name=NAME Config name
- --type=TYPE Config type
- -r, --recent=NUMBER Number of configs to show (default: 1)
```
bosh -e my-env configs
```
Should result in:
```
Using environment '192.168.56.6' as client 'admin'

Type     Name
cloud    default
~        custom-vm-types
cpi      default
runtime  default

3 configs

Succeeded
```

Config¶

bosh [GLOBAL-CLI-OPTIONS] config [--name=NAME] [--type=TYPE] [ID]

Show current config for either ID or both type and name.
- --name=NAME Config name
- --type=TYPE Config type
- ID Config ID
```
bosh -e my-env config --type=my-type --name=my-name
bosh -e my-env config 5
```

Update-Config¶

bosh [GLOBAL-CLI-OPTIONS] update-config [--type=TYPE] [--name=NAME] [--expected-latest-id=ID] [-v ...] [--var-file=VAR=PATH] [-l ...] [--vars-env=PREFIX] [--vars-store=PATH] [-o ...] PATH

Update config on the Director.
- --type=TYPE Config type, e.g. 'cloud', 'runtime', or 'cpi'
- --name=NAME Config name
- --expected-latest-id=ID Expected ID of latest config
- -v, --var=VAR=VALUE Set variable
- --var-file=VAR=PATH Set variable to file contents
- -l, --vars-file=PATH Load variables from a YAML file
- --vars-env=PREFIX Load variables from environment variables (e.g.: 'MY' to load MY_var=value)
- --vars-store=PATH Load/save variables from/to a YAML file
- -o, --ops-file=PATH Load manifest operations from a YAML file
- PATH Path to a YAML config file
```
bosh -e my-env update-config config.yml --type=cloud
bosh -e my-env update-config config.yml --type=cloud --name=network1
```

Delete-Config¶

bosh [GLOBAL-CLI-OPTIONS] delete-config [--type=TYPE] [--name=NAME] [ID]

Delete config on the Director.
- --name=NAME Config name
- --type=TYPE Config type
- ID Config ID
```
bosh -e my-env delete-config --type=my-type
bosh -e my-env delete-config --type=my-type --name=my-name
```

Diff-Config¶

bosh [GLOBAL-CLI-OPTIONS] diff-config [--from-id=ID] [--to-id=ID] [--from-content=PATH] [--to-content=PATH]

Diff two configs by ID or content.
- --from-id=ID ID of first config to compare
- --to-id=ID ID of second config to compare
- --from-content=PATH path to first config file to compare
- --to-content=PATH path to second config file to compare
```
bosh -e my-env diff-config --from-id=1 --to-id=2
bosh -e my-env diff-config --from-content=/path/to/file1 --to-content=/path/to/file2
```

Cloud config¶

See Cloud config.

Cloud-Config¶

bosh [GLOBAL-CLI-OPTIONS] cloud-config (Alias: cc)

Show current cloud config on the Director.
- --name=NAME Cloud-Config name (default: ''); Available as of director version v273.0.0

Update-Cloud-Config¶

bosh [GLOBAL-CLI-OPTIONS] update-cloud-config [-v ...] [--var-file=VAR=PATH] [-l ...] [--vars-env=PREFIX] [--vars-store=PATH] [-o ...] PATH (Alias: ucc)

Update current cloud config on the Director.
- -v, --var=VAR=VALUE Set variable
- --var-file=VAR=PATH Set variable to file contents
- -l, --vars-file=PATH Load variables from a YAML file
- --vars-env=PREFIX Load variables from environment variables (e.g.: 'MY' to load MY_var=value)
- --vars-store=PATH Load/save variables from/to a YAML file
- -o, --ops-file=PATH Load manifest operations from a YAML file
- --name=NAME Cloud-Config name (default: ''); Available as of director version v273.0.0
- PATH Path to a cloud config file
```
bosh -e my-env ucc cc.yml
```

Runtime config¶

See Runtime config.

Runtime-Config¶

bosh [GLOBAL-CLI-OPTIONS] runtime-config [--name=NAME] (Alias: rc)

Show current runtime config on the Director.
- --name=NAME Runtime-Config name (default: '')

Update-Runtime-Config¶

bosh [GLOBAL-CLI-OPTIONS] update-runtime-config [-v ...] [--var-file=VAR=PATH] [-l ...] [--vars-env=PREFIX] [--vars-store=PATH] [-o ...] [--no-redact] [--name=NAME] PATH (Alias: urc)

Update current runtime config on the Director.
- -v, --var=VAR=VALUE Set variable
- --var-file=VAR=PATH Set variable to file contents
- -l, --vars-file=PATH Load variables from a YAML file
- --vars-env=PREFIX Load variables from environment variables (e.g.: 'MY' to load MY_var=value)
- --vars-store=PATH Load/save variables from/to a YAML file
- -o, --ops-file=PATH Load manifest operations from a YAML file
- --no-redact Show non-redacted manifest diff
- --name=NAME Runtime-Config name (default: '')
- PATH Path to a runtime config file
```
bosh -e my-env urc runtime.yml
```

CPI config¶

See CPI config.

CPI-Config¶

bosh [GLOBAL-CLI-OPTIONS] cpi-config

Show current CPI config on the Director.

Update-CPI-Config¶

bosh [GLOBAL-CLI-OPTIONS] update-cpi-config [-v ...] [--var-file=VAR=PATH] [-l ...] [--vars-env=PREFIX] [--vars-store=PATH] [-o ...] [--no-redact] PATH

Update current CPI config on the Director.
- -v, --var=VAR=VALUE Set variable
- --var-file=VAR=PATH Set variable to file contents
- -l, --vars-file=PATH Load variables from a YAML file
- --vars-env=PREFIX Load variables from environment variables (e.g.: 'MY' to load MY_var=value)
- --vars-store=PATH Load/save variables from/to a YAML file
- -o, --ops-file=PATH Load manifest operations from a YAML file
- --no-redact Show non-redacted manifest diff
- PATH Path to a CPI config file
```
bosh -e my-env update-cpi-config cpis.yml
```

Deployments¶

bosh [GLOBAL-CLI-OPTIONS] deployments (Alias: ds)

Lists deployments tracked by the Director. Shows their names, used releases and stemcells.

bosh -e my-env ds

Should result in:

Using environment '192.168.56.6' as client 'admin'

Name                                Release(s)                Stemcell(s)                                         Team(s)
cf                                  binary-buildpack/1.0.9    bosh-warden-boshlite-ubuntu-xenial-go_agent/621.74  -
                                    capi/1.21.0
                                    cf-mysql/34
                                    cf-smoke-tests/11
                                    cflinuxfs2-rootfs/1.52.0
                                    consul/155
                                    diego/1.8.1
                                    etcd/94
                                    garden-runc/1.2.0
                                    loggregator/78
                                    nats/15
                                    routing/0.145.0
                                    statsd-injector/1.0.20
                                    uaa/25
service-instance_0d4140a0-42b7-...  mysql/0.6.0               bosh-warden-boshlite-ubuntu-xenial-go_agent/621.74  -

2 deployments

Succeeded

Deployment¶

bosh [GLOBAL-CLI-OPTIONS] deployment (Alias: dep)

Shows general deployment information for a given deployment.

Can be used to determine if Director has a deployment with a given name.

bosh -e vbox -d cf dep

Should result in:

Using environment '192.168.56.6' as client 'admin'

Name  Release(s)              Stemcell(s)                                         Team(s)  Cloud Config
cf    binary-buildpack/1.0.9  bosh-warden-boshlite-ubuntu-xenial-go_agent/621.74  -        latest
      capi/1.21.0
      cf-mysql/34
      cf-smoke-tests/11
      uaa/25
      dns/3
      ...

1 deployments

Succeeded

Deploy¶

bosh [GLOBAL-CLI-OPTIONS] deploy [-v ...] [--var-file=VAR=PATH] [-l ...] [--vars-env=PREFIX] [--vars-store=PATH] [-o ...] [--no-redact] [--recreate] [--recreate-persistent-disks] [--fix] [--skip-drain=[INSTANCE-GROUP[/INSTANCE-ID]]] [--canaries=NUMBER or PERCENTAGE] [--max-in-flight=NUMBER or PERCENTAGE] [--dry-run] [--force-latest-variables] PATH

Create or update specified deployment according to the provided manifest. Operation files and variables can be provided to adjust and fill in manifest before deploy begins.

Currently name provided via --deployment (-d) flag must match name specified in the manifest.
- -v, --var=VAR=VALUE Set variable
- --var-file=VAR=PATH Set variable to file contents
- -l, --vars-file=PATH Load variables from a YAML file
- --vars-env=PREFIX Load variables from environment variables (e.g.: 'MY' to load MY_var=value)
- --vars-store=PATH Load/save variables from/to a YAML file
- -o, --ops-file=PATH Load manifest operations from a YAML file
- --no-redact Show non-redacted manifest diff
- --recreate Recreate all VMs in deployment. It will recreate regardless of whether there is a manifest change
- --recreate-persistent-disks Recreate all persistent disks in deployment. It will recreate regardless of whether there is a manifest change
- --fix Recreate an instance with an unresponsive agent instead of erroring
- --fix-releases Reupload releases in manifest and replace corrupt or missing jobs/packages
- --skip-drain=[INSTANCE-GROUP[/INSTANCE-ID]] Skip running drain and pre-stop scripts for specific instance groups
- --canaries=NUMBER or PERCENTAGE Override manifest values for canaries
- --max-in-flight=NUMBER or PERCENTAGE Override manifest values for max_in_flight
- --dry-run Renders job templates without altering a deployment. It will save some state in the director database (like ip reservations) which will be reused on the next deploy
- --force-latest-variables Causes the director to retreive the latest value of all variables from the config server, overriding their update strategies. Available as of director version v279.0.0
- PATH Path to a manifest file
```
bosh -e vbox -d cf deploy cf.yml -v system_domain=sys.example.com -o large-footprint.yml
```

Note

As of CLI v7.5.0+ the deploy command supports the usage of global flags which are applied to every deploy command automatically. Please refer to Deploy config for more information.

Delete-Deployment¶

bosh [GLOBAL-CLI-OPTIONS] delete-deployment [--force] (Alias: deld)

Deletes specified deployment.
- --force Ignore errors
Note that if you've deleted your deployment, not all resources may have been freed. For example "deleted" persistent disks will be deleted after a few days to avoid accidental data loss. See Persistent and Orphaned Disks for more details.

Succeeds even if deployment is not found.
```
bosh -e vbox -d cf deld
bosh -e vbox -d cf deld --force
```

Instances¶

bosh [GLOBAL-CLI-OPTIONS] instances [-i] [--vitals] [-p] [-f] (Alias: is)

Lists all instances managed by the Director or in a single deployment. Show instance names, IPs, and VM and process health.
- -i, --details Show details including VM CID, persistent disk CID, etc.
- --vitals Show vitals
- -p, --ps Show processes
- -f, --failing Only show failing instances
```
bosh -e vbox is -i
bosh -e vbox is --ps --vitals
bosh -e vbox -d cf is
bosh -e vbox -d cf is --ps
bosh -e vbox -d cf is --ps --vitals
```

Manifest¶

bosh [GLOBAL-CLI-OPTIONS] manifest (Alias: man)

Prints deployment manifest to stdout. In case a deployment failed, it will print the manifest of the last succesful deploy.
```
bosh -e vbox -d cf man > /tmp/manifest.yml
```

Recreate¶

bosh [GLOBAL-CLI-OPTIONS] recreate [--skip-drain] [--fix] [--canaries=NUMBER or PERCENTAGE] [--max-in-flight=NUMBER or PERCENTAGE] [--dry-run] [--converge] [--no-converge] [INSTANCE-GROUP[/INSTANCE-ID]]

Recreates VMs for specified instances. Follows typical instance lifecycle.
- --skip-drain skip running drain scripts; Also skip pre-stop scripts as of director version v270.0.0
- --fix recover an instance with an unresponsive agent instead of erroring
- --canaries=NUMBER or PERCENTAGE override manifest values for canaries
- --max-in-flight=NUMBER or PERCENTAGE override manifest values for max_in_flight
- --dry-run run through as many operations as possible without altering deployment
- --converge converge the deployment with the last successful deployment state. This flag is optional and is the default behavior. See Deployment Convergence for more details
- --no-converge update only the specified instance with current instance state. See Deployment Convergence for more details
Warning

In case of a failed deployment, running bosh recreate with the default behavior of --converge will converge to the last successfully deployed state, not the intended state of the failed deployment. See Deployment Convergence.

Restart¶

bosh [GLOBAL-CLI-OPTIONS] restart [--skip-drain] [--canaries=NUMBER or PERCENTAGE] [--max-in-flight=NUMBER or PERCENTAGE] [--converge] [--no-converge] [INSTANCE-GROUP[/INSTANCE-ID]]

Restarts jobs (processes) on specified instances. Does not affect VM state.
- --skip-drain skip running drain scripts; Also skip pre-stop scripts as of director version v270.0.0
- --canaries=NUMBER or PERCENTAGE override manifest values for canaries
- --max-in-flight=NUMBER or PERCENTAGE override manifest values for max_in_flight
- --converge converge the deployment with the last successful deployment state. This flag is optional and is the default behavior. See Deployment Convergence for more details
- --no-converge update only the specified instance with current instance state. See Deployment Convergence for more details
Warning

In case of a failed deployment, running bosh restart without --no-converge will converge to the last successfully deployed state, not the intended state of the failed deployment. See Deployment Convergence.

Start¶

bosh [GLOBAL-CLI-OPTIONS] start [--canaries=NUMBER or PERCENTAGE] [--max-in-flight=NUMBER or PERCENTAGE] [--converge] [--no-converge] [INSTANCE-GROUP[/INSTANCE-ID]]

Starts jobs (processes) on specified instances. Does not affect VM state.
- --canaries=NUMBER or PERCENTAGE override manifest values for canaries
- --max-in-flight=NUMBER or PERCENTAGE override manifest values for max_in_flight
- --converge converge the deployment with the last successful deployment state. This flag is optional and is the default behavior. See Deployment Convergence for more details
- --no-converge update only the specified instance with current instance state. See Deployment Convergence for more details
Warning

In case of a failed deployment, running bosh start without --no-converge will converge to the last successfully deployed state, not the intended state of the failed deployment. See Deployment Convergence.

Stop¶

bosh [GLOBAL-CLI-OPTIONS] stop [--skip-drain] [--canaries=NUMBER or PERCENTAGE] [--max-in-flight=NUMBER or PERCENTAGE] [--converge] [--no-converge] [INSTANCE-GROUP[/INSTANCE-ID]]

Stops jobs (processes) on specified instances. Does not affect VM state unless --hard flag is specified.
- --hard force VM deletion (keeping persistent disk)
- --skip-drain skip running drain scripts; Also skip pre-stop scripts as of director version v270.0.0
- --canaries=NUMBER or PERCENTAGE override manifest values for canaries
- --max-in-flight=NUMBER or PERCENTAGE override manifest values for max_in_flight
- --converge converge the deployment with the last successful deployment state. This flag is optional and is the default behavior. See Deployment Convergence for more details
- --no-converge update only the specified instance with current instance state. See Deployment Convergence for more details
Warning

In case of a failed deployment, running bosh stop without --no-converge will converge to the last successfully deployed state, not the intended state of the failed deployment. See Deployment Convergence.

Ignore¶

bosh [GLOBAL-CLI-OPTIONS] ignore INSTANCE-GROUP/INSTANCE-ID

Ignores instance from being affected by other commands such as bosh deploy. See details.

Unignore¶

bosh -e my-env -d my-dep unignore INSTANCE-GROUP/INSTANCE-ID

Unignores instance from being affected by other commands such as bosh deploy.

Logs¶

bosh [GLOBAL-CLI-OPTIONS] logs [--dir=DIR] [-f] [--num=NUMBER] [-q] [--job=NAME] [--only=FILTERS] [--agent] [--gw-disable] [--gw-user=USER] [--gw-host=HOST] [--gw-private-key=KEY] [--gw-socks5=URL] [INSTANCE-GROUP[/INSTANCE-ID]]

Downloads logs from one or more instances.
- --dir=DIR Destination directory (default: .)
- -f, --follow Follow logs via SSH
- --num=NUMBER Last number of lines
- -q, --quiet Suppresses printing of headers when multiple files are being examined
- --job=NAME Limit to only specific jobs (can only be used in combination with --follow)
- --only=FILTERS Filter logs (comma-separated)
- --agent Include only agent logs
- --system Include only system logs
- --all-logs Include all logs (agent, system, and job logs)
- --gw-disable Disable usage of gateway connection [$BOSH_GW_DISABLE]
- --gw-user=USER Username for gateway connection [$BOSH_GW_USER]
- --gw-host=HOST Host for gateway connection [$BOSH_GW_HOST]
- --gw-private-key=KEY Private key path for gateway connection [$BOSH_GW_PRIVATE_KEY]
- --gw-socks5=URL SOCKS5 URL [$BOSH_ALL_PROXY]
- --director Target the command at the BOSH director (or other type of VM deployed via create-env)
- --agent-endpoint=URL Address to connect to the agent's HTTPS endpoint (used with --director). Corresponds to the cloud_provider.mbus property of a BOSH director manifest. [$BOSH_AGENT_ENDPOINT]
- --agent-certificate=CERTIFICATE_CONTENT CA certificate to validate the agent's HTTPS endpoint (used with --director). Corresponds to the cloud_provider.cert property of a BOSH director manifest. [$BOSH_AGENT_CERTIFICATE]
See Location and use of logs for details.
```
bosh -e vbox -d cf logs diego-cell/209c42e5-3c1a-432a-8445-ab8d7c9f69b0
bosh -e vbox -d cf logs diego-cell/209c42e5-3c1a-432a-8445-ab8d7c9f69b0 --follow --job=rep --job=silkd
bosh -e vbox -d cf logs diego-cell/209c42e5-3c1a-432a-8445-ab8d7c9f69b0 --only='*/*stderr.log'
bosh -e vbox -d cf logs diego-cell/209c42e5-3c1a-432a-8445-ab8d7c9f69b0 --agent --only=current --only=sync-time.out
bosh -e vbox -d cf logs diego-cell/209c42e5-3c1a-432a-8445-ab8d7c9f69b0 --system --only=kern.log --only=syslog --only=auth.log
bosh -e vbox -d cf logs -f
bosh -e vbox -d cf logs -f --num=1000
bosh -e vbox -d cf logs -f --system --num=1000
```
Note

The --system and --all-logs flags require version v7.2.0 or later of the BOSH CLI.

Note

Downloading --system or --all-logs logs requires special Agent support, and only works with Agents v2.516.0 or newer. Following (with --follow) --system or --all-logs logs works with any Agent version.

Events¶

bosh [GLOBAL-CLI-OPTIONS] events [--before-id=ID] [--before=TIMESTAMP] [--after=TIMESTAMP] [--task=ID] [--instance=ID] [--event-user=USER] [--action=ACTION] [--object-type=TYPE] [--object-name=NAME]

Lists events.

See Events for details.
- --before-id=ID show events with ID less than the given ID
- --before=TIMESTAMP show events before the given timestamp (ex: 2016-05-08 17:26:32)
- --after=TIMESTAMP show events after the given timestamp (ex: 2016-05-08 17:26:32)
- --task=ID show events with the given task ID
- --instance=ID show events with given instance
- --event-user=USER show events with given user
- --action=ACTION show events with given action
- --object-type=TYPE show events with given object type
- --object-name=NAME show events with given object name
```
bosh -e vbox events --instance diego-cell/209c42e5-3c1a-432a-8445-ab8d7c9f69b0
bosh -e vbox events --instance diego-cell/209c42e5-3c1a-432a-8445-ab8d7c9f69b0 --task 281
bosh -e vbox events -d my-dep
bosh -e vbox events --before-id=1298284
bosh -e vbox events --before="2016-05-08 17:26:32 UTC" --after="2016-05-07 UTC"
```

Event¶

bosh [GLOBAL-CLI-OPTIONS] event ID

Shows single event details.

Variables¶

bosh [GLOBAL-CLI-OPTIONS] variables (Alias: vars)

List variables referenced by the deployment.

VMs¶

Vms¶

bosh [GLOBAL-CLI-OPTIONS] vms [--vitals] [--cloud-properties]

Lists all VMs managed by the Director or VMs in a single deployment. Show instance names, IPs and VM CIDs.
- --vitals Show vitals
- --cloud-properties Show cloud properties
```
bosh -e vbox vms
bosh -e vbox -d cf vms
bosh -e vbox -d cf vms --vitals
```

Delete-Vm¶

bosh [GLOBAL-CLI-OPTIONS] delete-vm CID

Deletes VM without going through typical instance lifecycle. Clears out VM reference from a Director database if referenced by any instance.
```
bosh -e vbox -d cf delete-vm i-fs384238fjwjf8
```

Orphaned-Vms¶

bosh [GLOBAL-CLI-OPTIONS] orphaned-vms

List all the orphaned VMs for all deployments.
```
bosh -e vbox orphaned-vms
```

Disks¶

bosh [GLOBAL-CLI-OPTIONS] disks [-o ]

Lists disks.
- -o, --orphaned List orphaned disks

Orphan-Disk¶

bosh [GLOBAL-CLI-OPTIONS] orphan-disk CID

Orphans a disk attached to an instance. You can get disk's CID from bosh instances --details.
```
bosh -e vbox orphan-disk xxxx-xxxx-xxxx
```

Attach-Disk¶

bosh [GLOBAL-CLI-OPTIONS] attach-disk [--disk-properties=PROPERTIES] INSTANCE-GROUP/INSTANCE-ID DISK-CID

Attaches disk to an instance, replacing and orphaning the currently attached disk (if any).
- --disk-properties=PROPERTIES Disk properties to use for the new disk. Use 'copy' to copy the properties from the currently attached disk
```
bosh -e vbox -d cf attach-disk postgres/209c42e5-3c1a-432a-8445-ab8d7c9f69b0 vol-shw8f293f2f2
```

Delete-Disk¶

bosh [GLOBAL-CLI-OPTIONS] delete-disk CID

Deletes orphaned disk.
```
bosh -e vbox -d cf delete-disk vol-shw8f293f2f2
```

SSH¶

bosh [GLOBAL-CLI-OPTIONS] ssh [-c=CMD] [--opts=OPTS] [-r] [--gw-disable] [--gw-user=USER] [--gw-host=HOST] [--gw-private-key=KEY] [--gw-socks5=URL] [INSTANCE-GROUP[/INSTANCE-ID]]

SSH into one or more instances.
- -c, --command=CMD Command
- --opts=OPTS specify pass-through options to ssh; useful for port forwarding
- -r, --results Collect results into a table instead of streaming
- --gw-disable Disable usage of gateway connection [$BOSH_GW_DISABLE]
- --gw-user=USER Username for gateway connection [$BOSH_GW_USER]
- --gw-host=HOST Host for gateway connection [$BOSH_GW_HOST]
- --gw-private-key=KEY Private key path for gateway connection [$BOSH_GW_PRIVATE_KEY]
- --gw-socks5=URL SOCKS5 URL [$BOSH_ALL_PROXY]
- --director Target the command at the BOSH director (or other type of VM deployed via create-env)
- --agent-endpoint=URL Address to connect to the agent's HTTPS endpoint (used with --director). Corresponds to the cloud_provider.mbus property of a BOSH director manifest. [$BOSH_AGENT_ENDPOINT]
- --agent-certificate=CERTIFICATE_CONTENT CA certificate to validate the agent's HTTPS endpoint (used with --director). Corresponds to the cloud_provider.cert property of a BOSH director manifest. [$BOSH_AGENT_CERTIFICATE]
```
# execute command on all instances in a deployment
bosh -e vbox -d cf ssh -c 'uptime'

# execute command on one instance group
bosh -e vbox -d cf ssh diego-cell -c 'uptime'

# execute command on a single instance
bosh -e vbox -d cf ssh diego-cell/209c42e5-3c1a-432a-8445-ab8d7c9f69b0 -c 'uptime'

# execute command with passwordless sudo
bosh -e vbox -d cf ssh diego-cell -c 'sudo lsof -i|grep LISTEN'

# present output in a table by instance
bosh -e vbox -d cf ssh -c 'uptime' -r

# port forward UAA port locally
bosh -e vbox -d cf ssh uaa/0 --opts ' -L 8080:localhost:8080'
```

SCP¶

bosh [GLOBAL-CLI-OPTIONS] scp [-r] [--gw-disable] [--gw-user=USER] [--gw-host=HOST] [--gw-private-key=KEY] [--gw-socks5=URL] PATH...

SCP to/from one or more instances.
- --recursive (-r) copy directory recursively
- --gw-disable Disable usage of gateway connection [$BOSH_GW_DISABLE]
- --gw-user=USER Username for gateway connection [$BOSH_GW_USER]
- --gw-host=HOST Host for gateway connection [$BOSH_GW_HOST]
- --gw-private-key=KEY Private key path for gateway connection [$BOSH_GW_PRIVATE_KEY]
- --gw-socks5=URL SOCKS5 URL [$BOSH_ALL_PROXY]
- --director Target the command at the BOSH director (or other type of VM deployed via create-env)
- --agent-endpoint=URL Address to connect to the agent's HTTPS endpoint (used with --director). Corresponds to the cloud_provider.mbus property of a BOSH director manifest. [$BOSH_AGENT_ENDPOINT]
- --agent-certificate=CERTIFICATE_CONTENT CA certificate to validate the agent's HTTPS endpoint (used with --director). Corresponds to the cloud_provider.cert property of a BOSH director manifest. [$BOSH_AGENT_CERTIFICATE]
```
# copy file from this machine to machines a deployment
bosh -e vbox -d cf scp ~/Downloads/script.sh :/tmp
bosh -e vbox -d cf scp ~/Downloads/script.sh diego-cell:/tmp
bosh -e vbox -d cf scp ~/Downloads/script.sh diego-cell/209c42e5-3c1a-432a-8445-ab8d7c9f69b0:/tmp
bosh -e vbox -d cf scp ~/Downloads/script.ps1 windows_diego_cell:c:/temp/script

# copy file from remote machines in a deployment to this machine
bosh -e vbox -d cf scp :/tmp/script.sh ~/Downloads
bosh -e vbox -d cf scp diego-cell:/tmp/script.sh ~/Downloads
bosh -e vbox -d cf scp diego-cell/209c42e5-3c1a-432a-8445-ab8d7c9f69b0:/tmp/script.sh ~/Downloads
bosh -e vbox -d cf scp windows_diego_cell:c:/temp/script/script.ps1:~/Downloads

# copy files from each instance into instance specific local directory
bosh -e vbox -d cf scp diego-cell:/tmp/logs/ /tmp/logs/((instance_id))
```

PCAP¶

bosh [GLOBAL-CLI-OPTIONS] pcap -o=OUTPUT [-i=INTERFACE] [-f=FILTER] [-s=SNAPLEN] [--stop-timeout=TIMEOUT] [--gw-disable] [--gw-user=USER] [--gw-host=HOST] [--gw-private-key=KEY] [--gw-socks5=URL] [INSTANCE-GROUP[/INSTANCE-ID]...]

Allows to perform network capture on one or multiple bosh instances. Capturing network traffic can help to analyse issues like network congestion, high latency, packet loss, or other network-related problems.

-o, --output=OUTPUT File to write pcap to
-i, --interface=INTERFACE Specifies the network interface to listen on (default: eth0)
-f, --filter=FILTER Filter to refine traffic capture. Any filter string input should not exceed 5000 characters in length
-s, --snaplen=SNAPLEN Amount of data to be captured from each packet rather than the default of 65535 bytes
--stop-timeout=TIMEOUT Timeout to wait for data to flush before session stop (default: 5s)
--gw-disable Disable usage of gateway connection [$BOSH_GW_DISABLE]
--gw-user=USER Username for gateway connection [$BOSH_GW_USER]
--gw-host=HOST Host for gateway connection [$BOSH_GW_HOST]
--gw-private-key=KEY Private key path for gateway connection [$BOSH_GW_PRIVATE_KEY]

--gw-socks5=URL SOCKS5 URL [$BOSH_ALL_PROXY]

# capture network traffic on all instances in a deployment
bosh -e vbox -d cf pcap -o capture.pcap

# don't ask for user confirmation and establish 100 connections in parallel (default: 5)
bosh -e vbox -d cf pcap -o capture.pcap --non-interactive --parallel 100

# capture network traffic on one instance group
bosh -e vbox -d cf pcap router -o capture.pcap

# capture network traffic on a single instance
bosh -e vbox -d cf pcap router/209c42e5-3c1a-432a-8445-ab8d7c9f1111 -o capture.pcap

# capture network traffic on multiple capture groups or instances in a deployment
bosh -e vbox -d cf pcap nats router/0 -o capture.pcap

# capture network traffic with filter for a specific source host
bosh -e vbox -d cf pcap router -f "src host 192.168.1.11" -o capture.pcap

# capture network traffic with snap length 64 to save the first 64 bytes of each packet and filter for specific hosts
bosh -e vbox -d cf pcap router -f "host 192.168.1.11 or host 192.168.1.15" -s 64 -o capture.pcap

Errands¶

bosh [GLOBAL-CLI-OPTIONS] errands (Alias: es)

Lists all errands defined by the deployment.

bosh -e vbox -d cf es

Should result in:

Using environment '192.168.56.6' as '?'

Using deployment 'cf'

Name
smoke-tests

1 errands

Succeeded

Run-Errand¶

bosh [GLOBAL-CLI-OPTIONS] run-errand [--instance=INSTANCE-GROUP[/INSTANCE-ID]] [--keep-alive] [--when-changed] [--download-logs] [--logs-dir=DIR] NAME

Runs errand job by name.

--instance=INSTANCE-GROUP[/INSTANCE-ID] Instance or group the errand should run on (must specify errand by release job name)
--keep-alive Use existing VM to run an errand and keep it after completion
--when-changed Run errand only if errand configuration has changed or if the previous run was unsuccessful
--download-logs Download logs
--logs-dir=DIR Destination directory for logs (default: .)

See Errands for details.

bosh -e vbox -d cf run-errand smoke-tests
bosh -e vbox -d cf run-errand smoke-tests --keep-alive
bosh -e vbox -d cf run-errand smoke-tests --when-changed

# execute errand on all instances that have colocated status errand
bosh -e vbox -d zookeeper run-errand status

# execute errand on one instance
bosh -e vbox -d zookeeper run-errand status --instance zookeeper/3e977542-d53e-4630-bc40-72011f853cb5

# execute errand on one instance within an instance group
# (note that select instance may not necessarily be first based on its index)
bosh -e vbox -d zookeeper run-errand status --instance zookeeper/first

# execute errand on all instance in an instance group
bosh -e vbox -d zookeeper run-errand status --instance zookeeper

# execute errand on two instances
bosh -e vbox -d zookeeper run-errand status \
  --instance zookeeper/671d5b1d-0310-4735-8f58-182fdad0e8bc \
  --instance zookeeper/3e977542-d53e-4630-bc40-72011f853cb5

Tasks¶

bosh [GLOBAL-CLI-OPTIONS] tasks [--recent=NUMBER] [-a] (Alias: ts)

Lists active and previously ran tasks.

-r,--recent=NUMBER Show 30 recent tasks. Use '=' to specify the number of tasks to show
-a, --all Include all task types (ssh, logs, vms, etc)

# currently active tasks
bosh -e vbox ts

# currently active tasks for my-dep deployment
bosh -e vbox -d my-dep ts

Should result in:

Using environment '192.168.56.6' as '?'

#   State  Started At                    Finished At                   User   Deployment   Description                   Result

27  done   Thu Feb 16 19:16:15 UTC 2017  Thu Feb 16 19:20:33 UTC 2017  admin  cockroachdb  create deployment             /deployments/cockroachdb
26  done   Thu Feb 16 18:54:32 UTC 2017  Thu Feb 16 18:55:27 UTC 2017  admin  cockroachdb  delete deployment cockroachd  /deployments/cockroachdb
...

110 tasks

Succeeded

# show last 30 tasks
bosh -e vbox ts -r --all

# show last 1000 tasks
bosh -e vbox ts -r=1000

Task¶

bosh [GLOBAL-CLI-OPTIONS] task [--event] [--cpi] [--debug] [--result] [-a] [ID] (Alias: t)

Shows single task details. Continues to follow task if it did not finish. Ctrl^C does not cancel the task.
- --event Track event log
- --cpi Track CPI log
- --debug Track debug log
- --result Track result log
- -a, --all Include all task types (ssh, logs, vms, etc)
- ID ID of the task
```
bosh -e vbox t 281
bosh -e vbox t 281 --debug
```

Cancel-Task¶

bosh [GLOBAL-CLI-OPTIONS] cancel-task ID (Alias: ct)

Cancel task at its next checkpoint. Does not wait until task is cancelled.
```
bosh -e vbox ct 281
```

Cancel-Tasks¶

bosh [GLOBAL-CLI-OPTIONS] cancel-tasks [--type=TYPE] [--state=STATE] (Alias: cts)

Cancel multiple tasks by type and state at their next checkpoints.
- -t, --type=TYPE task types to cancel (cck_scan_and_fix, cck_apply, update_release, update_deployment, vms, etc.) (default is all types)
- -s, --state=STATE task states to cancel (queued, processing) (default: queued)
```
bosh -e vbox cts \
     -d my-dep \
     -t scan_and_fix \
     -t update_deployment \
     -t fetch_logs \
     -s queued \
     -s processing
```

Snapshots¶

bosh [GLOBAL-CLI-OPTIONS] snapshots [INSTANCE-GROUP/INSTANCE-ID]

Lists disk snapshots for given deployment.

Take-Snapshot¶

bosh [GLOBAL-CLI-OPTIONS] take-snapshot [INSTANCE-GROUP/INSTANCE-ID]

Takes snapshot for an instance or an entire deployment.

Delete-Snapshot¶

bosh [GLOBAL-CLI-OPTIONS] delete-snapshot CID

Deletes snapshot.
```
bosh -e vbox -d cf delete-snapshot snap-shw38ty83f2f2
```

Delete-Snapshots¶

bosh [GLOBAL-CLI-OPTIONS] delete-snapshots

Deletes snapshots for an entire deployment.

Deployment recovery¶

Update-Resurrection¶

bosh [GLOBAL-CLI-OPTIONS] update-resurrection on|off

Enables or disables resurrection globally. This state is not reflected in the bosh instances command's Resurrection column.

Note: Using bosh update-resurrection on will not enable resurrection unless the Resurrector has already been configured for the Director via the resurrector_enabled property.

See Automatic repair with Resurrector for details.

Cloud-Check¶

bosh [GLOBAL-CLI-OPTIONS] cloud-check [-a] [--resolution=RESOLUTION-VALUE] [-r] (Alias: cck)

Checks for resource consistency and allows interactive repair
- -a, --auto Resolve problems automatically
- --resolution=RESOLUTION-VALUE Apply resolution of given type
- -r, --report Only generate report; don't attempt to resolve problems
See Manual repair with Cloud Check for details.

Create-Recovery-Plan¶

bosh [GLOBAL-CLI-OPTIONS] create-recovery-plan PATH

Checks for resource consistency and interactively prompts for problem resolution by instance group. Optionally allows overriding the current value of max_in_flight for each instance group. This information is then written to a YAML file and is used by the bosh recover command.
- PATH Create recovery plan file at path
See Manual repair with recovery plans for details.

Recover¶

bosh [GLOBAL-CLI-OPTIONS] recover PATH

Using a recovery plan generated by bosh create-recovery-plan, this command displays a summary of the recovery plan, then applies the resolutions in the plan to the applicable instance groups, with their optional max_in_flight overrides.
- PATH Path to a recovery plan that will be used
See Manual repair with recovery plans for details.

Locks¶

bosh [GLOBAL-CLI-OPTIONS] locks

Lists current locks.

Network¶

Networks¶

bosh [GLOBAL-CLI-OPTIONS] networks [-o]

List networks created by deployments.
- -o, --orphaned List orphaned networks
```
bosh -e vbox networks
```

Delete-Network¶

bosh [GLOBAL-CLI-OPTIONS] delete-network NAME

Deletes a network created during deployment. Check CPI methods for more details
```
bosh -e vbox delete-network network-name
```

Misc¶

Clean-Up¶

bosh[GLOBAL-CLI-OPTIONS] clean-up [--all] [--dry-run] [--keep-orphaned-disks]

Cleans up unused resources but keeps orphaned disks and the two most recent versions of stemcells and releases.
- --all clean up all unused resources including orphaned disks.
- --dry-run list resources that would be cleaned up.
- --keep-orphaned-disks do not delete orphaned disks with --all.
Orphan disks get deleted after a few days by default. See Orphan Disks for more details.

Note: From BOSH v270.5.0, releases specified in runtime configs are considered 'in use' and won't be deleted by running bosh clean-up [--all].

Help¶

bosh help

Shows list of available commands and global options. Consider using -h flag for individual commands.

Interpolate Variables¶

bosh [GLOBAL-CLI-OPTIONS] interpolate [-v ...] [--var-file=PATH] [-l ...] [--vars-env=PREFIX] [--vars-store=PATH] [-o ...] [--path=OP-PATH] [--var-errs] [--var-errs-unused] PATH (Alias: int)

Interpolates variables into a manifest sending result to stdout. Operation files and variables can be provided to adjust and fill in manifest before doing a deploy.

-v, --var=VAR=VALUE Set variable
--var-file=VAR=PATH Set variable to file contents
-l, --vars-file=PATH Load variables from a YAML file
--vars-env=PREFIX Load variables from environment variables (e.g.: 'MY' to load MY_var=value)
--vars-store=PATH Load/save variables from/to a YAML file
-o, --ops-file=PATH Load manifest operations from a YAML file
--path=OP-PATH Extract value out of template (e.g.: /private_key)
--var-errs Expect all variables to be found, otherwise error
--var-errs-unused Expect all variables to be used, otherwise error
PATH Path to a template that will be interpolated

bosh int bosh-deployment/bosh.yml \
  --vars-store ./creds.yml \
  -o bosh-deployment/virtualbox/cpi.yml \
  -o bosh-deployment/virtualbox/outbound-network.yml \
  -o bosh-deployment/bosh-lite.yml \
  -o bosh-deployment/jumpbox-user.yml \
  -v director_name=vbox \
  -v internal_ip=192.168.56.6 \
  -v internal_gw=192.168.56.1 \
  -v internal_cidr=192.168.56.0/24 \
  -v network_name=vboxnet0 \
  -v outbound_network_name=NatNetwork

bosh int creds.yml --path /admin_password
# skh32i7rdfji4387hg

bosh int creds.yml --path /director_ssl/ca
# -----BEGIN CERTIFICATE-----
# ...

Command can be used in a generic way to generate CA and leaf certificates.

variables:
- name: default_ca
  type: certificate
  options:
    common_name: ca
- name: service_ssl
  type: certificate
  options:
    ca: default_ca
    common_name: ((internal_ip))
    alternative_names: [((internal_ip))]

bosh interpolate certs-tpl.yml -v internal_ip=1.2.3.4 --vars-store certs.yml --var-errs
bosh interpolate certs.yml --path /service_ssl/ca
bosh interpolate certs.yml --path /service_ssl/certificate
bosh interpolate certs.yml --path /service_ssl/private_key

HTTP Request¶

bosh [GLOBAL-CLI-OPTIONS] curl [--method=HTTP-METHOD] [--header=HTTP-HEADER] [--body=PATH-TO-FILE-WITH-HTTP-REQUEST-BODY] [--show-headers] PATH

Make an HTTP request to the BOSH Director REST API. Recommended to be used for debugging purposes only.
- --method (-X) specify the HTTP method. Allowed values: GET, POST, PUT, and DELETE. Defaults to GET
- --header (-H) add an HTTP header to the request in 'name: value' format. Can be specified multiple times for multiple headers.
- --body path to the file containing the HTTP request's body (for POST and PUT)
- --show-headers (-i) show HTTP headers in the response
- PATH URL path which can include query string

bosh curl /deployments
bosh curl /links?deployment=my-dep
bosh curl -H 'Content-Type: application/json' --body ./request-body.txt --method=POST /links