pcf-command.html.md.erb

---
title: Using 'pcf' Command Line utility with your services
owner: Services
---
The `pcf` utility provides a command line interface to <%= vars.platform_name %> for you to
deploy and test tiles. The `pcf` utility activates Tanzu Operations Manager access from CI pipelines, but
you might find it convenient to use the CLI rather than the Tanzu Operations Manager UI.

You can use the `pcf` utility to test your tile's BOSH errands
directly from your CLI, without going through Tanzu Operations Manager and BOSH. This reduces the time it takes to
deploy and test each iteration of your software components.

##<a id="install"></a> Installation

The `pcf` utility comes bundled with the Tile Generator tool. To
install the `pcf` utility, follow the
[Tile Generator installation instructions](tile-generator.html#how-to).

##<a id="auth"></a> Authentication

The `pcf` utility searches for a file called `metadata` in the current directory.
This file is expected to provide the URL and credentials to connect to
Tanzu Operations Manager, in the following format:

```yaml
---
opsmgr:
    url: https://opsmgr.example.com
    user name: admin
    password: <redacted>
```

The reason for this file naming is because this is how Concourse passes
credentials of a "claimed" <%= vars.platform_name %> pool resource to the CI pipeline scripts.
For interactive use, you have to create a `metadata`
file in the directory where you run the `pcf` command.

You must not create this file inside your GIT or other version control system repository, because you do not
  want to accidentally commit these credentials to version control.</p>

##<a id="commands"></a> Commands

The `pcf` utility implements many different commands.

To see available commands, run:

```bash
$ pcf --help
Usage: pcf [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  apply-changes
  cf-info
  changes
  configure
  delete-unused-products
  import
  install
  is-available
  is-installed
  logs
  products
  settings
  target
  test-errand
  uninstall
```

##<a id="ops-man-settings"></a> Verifying Tanzu Operations Manager settings

To see which products are available and installed in Tanzu Operations Manager, run:

```bash
$ pcf products
- p-bosh 1.7.0.0 (installed)
- cf 1.7.0-build.258 (installed)
- test-tile 0.3.95
```

To test if a specific product is available or installed from within a script, run:

```bash
$ pcf is-available test-tile && echo "Product test-tile is available"
$ pcf is-installed test-tile && echo "Product test-tile is installed"
```

To retrieve the settings for a specific product, run:

```bash
$ pcf settings test-tile
{
    "network_reference": "669e213111ab5aa1008a",
    "guid": "test-tile-be3e50cf26c530acca6e",
    "jobs": [
        {
            "instance": {
                "identifier": "instances"
            },
            "identifier": "compilation",
            "guid": "compilation-066a85d82fbcd936f9d7",
            "installation_name": "compilation",
            "vm_credentials": {
                "password": <redacted>,
                "salt": <redacted>,
                "identity": "vcap"
            }
        },
        {
            "guid": "deploy-all-b83a7cb7be00ebfd26d6",
            "vm_credentials": {
    ...
```

##<a id="deploy-tiles"></a> Deploying tiles

After your software is working correctly, deploy using `test-errand`, and you can go
through the real Tanzu Operations Manager deployment process from the CLI, just as you can
normally do through the Tanzu Operations Manager UI.

Import your .pivotal file into Tanzu Operations Manager:

```bash
$ pcf import sample/product/test-tile-0.0.2.pivotal
```

Install the uploaded version of your product:

```bash
$ pcf install test-tile 0.0.2
```

Where you normally configure the tile settings in the UI, you can use the `configure`
command to pass in any user-specified properties as a .yml file. This command
also sets the stemcell for the tile to the same one used by <%= vars.app_runtime_full %> (<%= vars.app_runtime_abbr %>),
to avoid uploading a tile-specific stemcell.

```bash
$ pcf configure test-tile sample/missing-properties.yml
- Using stemcell bosh-vsphere-esxi-ubuntu-trusty-go_agent version 3215
```

The property file looks like this:

```yaml
---
customer_name: Jimmy's Johnnys
street_address: Cartaway Alley
city: New Jersey
country: US
username: SpongeBob
password: { 'secret': Square'Pants }
app2:
  persistence_store_type: none
# In <%= vars.platform_name %> (formerly PCF) 1.8+, BOSH-job-specific configuration is supported:
jobs:
  a_job:
    # Job resource configuration:
    resource_config:
      persistent_disk:
        size_mb: "10240"
    # Job-specific property configuration:
    job_property: property_value
```

You must define any `secret` type property value as a hash, in curly brackets. When you specify a simple
string value for a text box of this type, it results in a `500 System Error` that is returned from
`pcf configure` property.

The `secret` type property values can contain special characters.

To see what changes are ready to be applied, run:

```bash
$ pcf changes
install: test-tile-207b165fcb7dc8b2597b
delete:
```

To apply these changes, run:

```bash
$ pcf apply-changes
  ===== 2016-04-21 18:45:05 UTC Running "bosh-init deploy /var/tempest/workspaces/default/deployments/bosh.yml"
  Deployment manifest: '/var/tempest/workspaces/default/deployments/bosh.yml'
  Deployment state: '/var/tempest/workspaces/default/deployments/bosh-state.json'

  Started validating
    Validating release 'bosh'... Finished (00:00:08)
    Validating release 'bosh-vsphere-cpi'... Finished (00:00:00)
    Validating release 'uaa'... Finished (00:00:06)
    Validating cpi release... Finished (00:00:00)
    Validating deployment manifest... Finished (00:00:00)
```

The `pcf apply-changes` property automatically tails the logs for the installation process
that it started. If it stops, for any reason, you can tail the logs
of the most recent installation:

```bash
$ pcf logs
```

##<a id="remove"></a> Removing tiles

To uninstall a tile, run:

```bash
$ pcf uninstall test-tile
```

If you accumulate a lot of uninstalled tiles or old versions, you can clean
up Tanzu Operations Manager's available products (and disk space):

```bash
$ pcf delete-unused-products
```

## <a id="access-ert"></a> Accessing <%= vars.app_runtime_abbr %>

To see details about the <%= vars.app_runtime_abbr %> of your <%= vars.platform_name %> environment, run:

```bash
$ pcf cf-info
- admin_password: <redacted>
- admin_username: admin
- apps_domain: cfapps-04.example.com
- system_domain: run-04.example.com
- system_services_password: <redacted>
- system_services_username: system_services
```

To target your `cf` command line interface at this <%= vars.app_runtime_abbr %> environment, run:

```bash
$ pcf target
Setting api endpoint to api.example.com...
OK

API endpoint:   https://api.example.com (API version: 2.52.0)
User:           admin
Org:            my-org
Space:          my-space
API endpoint: https://api.example.com
Authenticating...
OK

...
```