Using the PCF CLI

Installation

The CLI is packaged in the PCF Python package, so after running

pip install pcf

you should be able to execute the CLI from your command line provided your Pip packages are available in your $PATH:

$ pcf -h
Usage: pcf [--version] [--help] <command> [<args>...]

Particle Cloud Framework

Options:
-v, --version  Show PCF version.
-h, --help     Show this message and exit.

Commands:
apply      Set a desired state and apply changes
run        Set desired state to 'run' and apply changes
stop       Set desired state to 'stopped' and apply changes
terminate  Set desired state to 'terminated' and apply changes

Usage

By default, the CLI reads Particle and Quasiparticle definitions from a JSON file named pcf.json or a YAML file named pcf.yml located in the current working directory.

The following pcf.json file defines a new AWS KMS key Particle and accepts the same top-level fields that Particle and Quasiparticle definitions use in the PCF Python library:

{
    "pcf_name": "kms_example",
    "flavor": "kms_key",
    "aws_resource": {
        "Description": "an example key",
        "Tags": [
            {
                "TagKey": "InUse",
                "TagValue": false
            }
        ],
        "custom_config": {
            "key_name": "pcf_kms_example"
        }
    }
}

An equivalent pcf.yml file would look like the following:

---
pcf_name: kms_example
flavor: kms_key
aws_resource:
  Description: an example key
  Tags:
    - TagKey: InUse
      TagValue: false
  custom_config:
    key_name: pcf_kms_example

With this pcf.json file, you can run

$ pcf run kms_example

and PCF will run the kms_key Particle flavor’s apply method and set the desired state of your Particle to running.

You can then perform subsequent actions on the Particle’s state:

$ pcf stop kms_example
  ...

$ pcf terminate kms_example
  ...

Using a Custom Config File Name

If you would like to name your config files something besides pcf.json or pcf.yml, specify the relative path to your file using the –file or -f option to any command that sets a desired state. The file must have a valid .json or .yml file extension.

$ pcf run --file dev_infra.yml

Cascading Changes from the CLI

To instruct PCF to cascade changes when apply is called on your Particles or Quasiparticles, provide the –cascade or -c flag to the CLI when invoking a command that sets a desired state:

$ pcf stop --cascade my_quasiparticle