Skip to main content
📢 New post: Editor Superpowers for Phobos — Introducing the Language Server and VS Code Extension — Read more →

Commands

Available Commands​

Currently, the CLI supports the following commands:

tip

phobos [command] or phobos [command] -h will output the help menu for that specific command.

info

Commands and options may evolve between major versions. Options must come before any arguments.

Have a question?

Check the FAQ to see if there's already an answer.

Legend
  • *   required
  • !   deprecated
  • ... repeatable

Global Options​

disable-autocomplete​

Uninstall shell autocompletion.

enable-autocomplete​

Install shell autocompletion.

h, help​

Show help output.

log​

Set the verbosity of log output for debugging.
Values: debug, error, info, off, trace, warn
Default: off
Env: PHOBOS_CLI_LOG

no-color​

Disable colored output.
Default: false
Env: NO_COLOR

p, profile​

Profile to use from the configuration file.
Default: default
Env: PHOBOS_PROFILE

v, version​

Show the version information.

caller-identity command​

Get the caller's identity.

Returns information about the authenticated caller (User or ServiceAccount).

phobos caller-identity

Options​

json​

Show final output as JSON.

configure command​

Create or update a profile.

Subcommands:

  • delete - Remove a profile.
  • list - Show all profiles.

Creates or updates a profile. If no options are specified, the command prompts for values.

phobos configure \
  -http-endpoint "https://api.phobos.example.com" \
  -profile "prod-example"

Options​

http-endpoint​

The Phobos HTTP API endpoint.

insecure-tls-skip-verify​

Allow TLS but disable verification of the gRPC server's certificate chain and hostname. Only use for testing as it could allow connecting to an impersonated server.
Default: false

profile​

The name of the profile to set.

configure delete subcommand​

Remove a profile.

Removes a profile and its credentials with the given name.

phobos configure delete prod-example

configure list subcommand​

Show all profiles.

Displays all configured profiles and their endpoints.

phobos configure list

fmt command​

Reformat HCL configuration files.

Rewrites HCL configuration files to canonical format. All files with the .hcl extension in the current directory are formatted if no files are specified. Lists formatted files to standard output.

phobos fmt \
  -directory "test-pipelines" \
  -recursive \
  -write

Options​

check​

Exit with non-zero status if files need formatting.
Default: false
Conflicts: write

diff​

Display a diff of the formatting changes.
Default: false

directory​

Directory to format files in.
Default: .

recursive​

Format files in the specified directory and all subdirectories.
Default: false

write​

Write the formatted result to the file(s).
Default: true
Conflicts: check

organization command​

Manage organizations.

Subcommands:

  • create - Create an organization.
  • delete - Delete an organization.
  • get - Retrieve an organization.
  • list - Retrieve a paginated list of organizations.
  • update - Update an organization.

Organizations are the top-level isolation boundary in Phobos. They contain projects, where applications or components are managed and released.

organization create subcommand​

Create an organization.

Creates a new organization with the given name and description.

phobos organization create \
  -description "<description>" \
  -json \
  <name>

Options​

description​

Description for the new organization.

json​

Show final output as JSON.

organization delete subcommand​

Delete an organization.

Permanently removes an organization and all its projects and resources.

phobos organization delete prn:organization:<organization_name>

Options​

version​

Optimistic locking version. Usually not required.

organization get subcommand​

Retrieve an organization.

Retrieves details about an organization by name.

phobos organization get \
  -json \
  <name>

Options​

json​

Show final output as JSON.

organization list subcommand​

Retrieve a paginated list of organizations.

Lists organizations. Supports pagination, filtering and sorting the output.

phobos organization list \
  -search "<search_term>" \
  -limit 5 \
  -json

Options​

cursor​

The cursor string for manual pagination.

json​

Show final output as JSON.

limit​

Maximum number of result elements to return.
Default: 100

Filter to only organizations containing this substring in their name.

sort-by​

Sort by this field.
Values: UPDATED_AT_ASC, UPDATED_AT_DESC
Conflicts: sort-order

sort-order !​

Sort in this direction.
Values: ASC, DESC
Deprecated: use -sort-by
Conflicts: sort-by

organization update subcommand​

Update an organization.

Modifies an organization's description.

phobos organization update \
  -description "<description>" \
  prn:organization:<organization_name>

Options​

description​

Description for the organization.

json​

Show final output as JSON.

version​

Optimistic locking version. Usually not required.

pipeline command​

Manage pipelines.

Subcommands:

  • cancel - Cancel a pipeline.
  • create - Create a pipeline.
  • get - Retrieve a pipeline.
  • list - Retrieve a paginated list of pipelines.
  • validate - Validates a pipeline template.

Pipelines are a series of automated stages that run in order to build, test, and deploy your application. They are created from pipeline templates.

pipeline cancel subcommand​

Cancel a pipeline.

Stops a running or pending pipeline. Use -force to cancel a pipeline that is not responding.

phobos pipeline cancel <id>

Options​

force, f​

Force cancel the pipeline.
Default: false

pipeline create subcommand​

Create a pipeline.

Creates a new pipeline under the specified organization and project.

HCL variables may be passed in via supported options or exported to the environment with a 'PB_VAR_' prefix.

Variable parsing precedence:

  1. HCL variables from the environment.
  2. phobos.pbvars file from configuration's directory, if present.
  3. phobos.pbvars.json file from configuration's directory, if present.
  4. *.auto.pbvars, *.auto.pbvars.json files from the configuration's directory, if present.
  5. -pb-var-file option(s).
  6. -pb-var option(s).

NOTE: If the same variable is assigned multiple values, the last value found will be used. A -pb-var option will override the values from a *.pbvars file which will override values from the environment (PB_VAR_).

HCL Variable File Format (.pbvars)

# Simple string variable
region = "us-east-1"

# Number variable
instance_count = 3

# Boolean variable
enable_monitoring = true

# List variable
availability_zones = ["us-east-1a", "us-east-1b", "us-east-1c"]

# Map/Object variable
tags = {
  Environment = "production"
  Team        = "platform"
}

JSON Variable File Format (.pbvars.json)

{
  "region": "us-east-1",
  "instance_count": 3,
  "enable_monitoring": true,
  "availability_zones": ["us-east-1a", "us-east-1b", "us-east-1c"],
  "tags": {
    "Environment": "production",
    "Team": "platform"
  }
}
phobos pipeline create \
  -org-name "<org_name>" \
  -type "RUNBOOK" \
  -filename "<filename>" \
  <project_name>

Options​

annotation ...​

A key/value pair that will be associated with the pipeline.

directory​

Path to directory that contains the HCL input file.
Default: .

env-var ...​

Define an environment variable. Environment variables are expected to be in the format of key=value. Non key=value pairs will be ignored.

env-var-file ...​

Path to environment variable file. Environment variable files are expected to be in the format of key=value per line.

environment-name​

The name of the environment to which this pipeline will deploy resources to (only required for deployment pipelines).

filename​

Name of HCL input file.
Conflicts: template-id

follow​

Show live pipeline output.
Default: false
Conflicts: json

json​

Show final output as JSON.
Conflicts: follow

org-name *​

Name of parent organization for the new pipeline.

pb-var ...​

Define a HCL variable as a key=value. To supply a string, do -pb-var 'sample=this is a value'. Non key=value pairs will be ignored.

pb-var-file ...​

Path to a HCL variable file (*.pbvars or *.pbvars.json).

template-id​

ID of the pipeline template to use.
Conflicts: filename

type *​

The type of the pipeline.
Values: DEPLOYMENT, RUNBOOK

variable-set-revision​

Project variable set revision or 'latest' for latest variable set.

pipeline get subcommand​

Retrieve a pipeline.

Retrieves details about a pipeline, including its status, type, and stages.

phobos pipeline get <id>

Options​

json​

Show final output as JSON.

pipeline list subcommand​

Retrieve a paginated list of pipelines.

Lists pipelines. Supports pagination, filtering and sorting the output.

phobos pipeline list \
  -limit 5 \
  -org-name "<org_name>" \
  -project-name "<project_name>" \
  -json

Options​

cursor​

The cursor string for manual pagination.

json​

Show final output as JSON.

limit​

Maximum number of result elements to return.
Default: 100

org-name *​

The organization to limit search.

project-name *​

The project to limit search.

sort-by​

Sort by this field.
Values: COMPLETED_AT_ASC, COMPLETED_AT_DESC, CREATED_AT_ASC, CREATED_AT_DESC, STARTED_AT_ASC, STARTED_AT_DESC, UPDATED_AT_ASC, UPDATED_AT_DESC
Conflicts: sort-order

sort-order !​

Sort in this direction.
Values: ASC, DESC
Deprecated: use -sort-by
Conflicts: sort-by

pipeline validate subcommand​

Validates a pipeline template.

Checks a pipeline template for errors without creating a pipeline.

HCL variables are optional when using the validate command except for variables used in dynamic blocks. Variables may be passed in via supported options or exported to the environment with a 'PB_VAR_' prefix.

Variable parsing precedence:

  1. HCL variables from the environment.
  2. phobos.pbvars file from configuration's directory, if present.
  3. phobos.pbvars.json file from configuration's directory, if present.
  4. *.auto.pbvars, *.auto.pbvars.json files from the configuration's directory, if present.
  5. -pb-var-file option(s).
  6. -pb-var option(s).

NOTE: If the same variable is assigned multiple values, the last value found will be used. A -pb-var option will override the values from a *.pbvars file which will override values from the environment (PB_VAR_).

HCL Variable File Format (.pbvars)

# Simple string variable
region = "us-east-1"

# Number variable
instance_count = 3

# Boolean variable
enable_monitoring = true

# List variable
availability_zones = ["us-east-1a", "us-east-1b", "us-east-1c"]

# Map/Object variable
tags = {
  Environment = "production"
  Team        = "platform"
}

JSON Variable File Format (.pbvars.json)

{
  "region": "us-east-1",
  "instance_count": 3,
  "enable_monitoring": true,
  "availability_zones": ["us-east-1a", "us-east-1b", "us-east-1c"],
  "tags": {
    "Environment": "production",
    "Team": "platform"
  }
}
phobos pipeline validate -filename "<filename>"

Options​

directory​

Path to directory that contains the HCL input file.
Default: .

filename​

Name of HCL input file.
Default: pipeline.hcl

pb-var ...​

Define a HCL variable as a key=value. To supply a string, do -pb-var 'sample=this is a value'. Non key=value pairs will be ignored.

pb-var-file ...​

Path to a HCL variable file (*.pbvars or *.pbvars.json).

pipeline-template command​

Manage pipeline templates.

Subcommands:

  • create - Create a pipeline template.
  • delete - Delete a pipeline template.
  • get - Retrieve a pipeline template.
  • list - Retrieve a paginated list of pipeline templates.
  • upgrade - Upgrade deprecated syntax in a pipeline template to the current HCL syntax.

Pipeline templates are versioned HCL blueprints that define the stages required to run a pipeline. They are reusable across multiple pipelines.

pipeline-template create subcommand​

Create a pipeline template.

Creates a new pipeline template under the specified organization and project.

phobos pipeline-template create \
  -filename "<filename>" \
  -name "<name>" \
  -versioned=true \
  -semantic-version 0.0.1 \
  -org-name "<org_name>" \
  -project-name "<project_name>"

Options​

directory​

Path to directory that contains the HCL input file.
Default: .

filename​

Name of HCL input file.
Default: pipeline.hcl

json​

Show final output as JSON.

name​

Specify a name for a versioned pipeline template. (Required if -versioned is true.)

org-name *​

Name of organization for the new pipeline.

project-name *​

Name of project for the new pipeline.

semantic-version​

Specify a semantic version for a versioned pipeline template. (Required if -versioned is true.)

versioned​

Create a versioned pipeline template.
Default: false

visibility​

Visibility of the pipeline template.
Values: GLOBAL, ORGANIZATION, PROJECT
Default: PROJECT

pipeline-template delete subcommand​

Delete a pipeline template.

Deletes a pipeline template with the given ID. Force deletion should be used with caution as it will break all pipelines using this template.

phobos pipeline-template delete <id>

Options​

force​

Force delete the pipeline template.
Default: false

version​

Optimistic locking version. Usually not required.

pipeline-template get subcommand​

Retrieve a pipeline template.

Retrieves details about a pipeline template, including its version and visibility.

phobos pipeline-template get <id>

Options​

json​

Show final output as JSON.

pipeline-template list subcommand​

Retrieve a paginated list of pipeline templates.

Lists pipeline templates. Supports pagination, filtering and sorting the output.

phobos pipeline-template list \
  -limit 5 \
  -org-name "<org_name>" \
  -project-name "<project_name>" \
  -json

Options​

archived​

If supplied, filter by archived pipeline templates.

cursor​

The cursor string for manual pagination.

json​

Show final output as JSON.

latest​

If supplied, filter by latest pipeline templates.

limit​

Maximum number of result elements to return.
Default: 100

org-name *​

Name of parent organization for the new pipeline.

project-name *​

The project to limit search.

search​

Filter to only pipeline templates with this name prefix.

sort-by​

Sort by this field.
Values: UPDATED_AT_ASC, UPDATED_AT_DESC
Conflicts: sort-order

sort-order !​

Sort in this direction.
Values: ASC, DESC
Deprecated: use -sort-by
Conflicts: sort-by

versioned​

If supplied, filter by versioned or non-versioned pipeline templates.

pipeline-template upgrade subcommand​

Upgrade deprecated syntax in a pipeline template to the current HCL syntax.

The pipeline-template upgrade command upgrades deprecated syntax in pipeline templates to the current HCL syntax.

Currently, it converts legacy action_outputs references.

The deprecated action_outputs syntax: action_outputs.stage.<stage>.task.<task>.action.<action>.<output>

Is upgraded to the new pipeline syntax: pipeline.stage.<stage>.task.<task>.outputs.<output>

The command also injects the required output blocks into the referenced tasks using the this.action.<action>.outputs.<output> syntax.

By default, the file is modified in-place. Use -dry-run to see a unified diff of what would change without modifying anything.

phobos pipeline-template upgrade \
  -filename my-pipeline-template.hcl \
  -dry-run

phobos pipeline-template upgrade \
  -filename my-pipeline-template.hcl

Options​

directory​

Path to directory that contains the HCL input file.
Default: .

dry-run​

Show a unified diff of what would change without modifying anything.
Default: false

filename​

Name of HCL input file.
Default: pipeline.hcl

plugin command​

Manage plugins.

Subcommands:

  • create - Create a new plugin in the plugin registry.
  • delete - Delete a plugin from the plugin registry.
  • delete-platform - Delete a plugin platform from the plugin registry.
  • delete-version - Delete a plugin version from the plugin registry.
  • get - Retrieve a plugin from the plugin registry.
  • get-platform - Retrieve a plugin platform from the plugin registry.
  • get-version - Retrieve a plugin version from the plugin registry.
  • install - Install a plugin from a remote registry.
  • launch - Launch a built-in plugin.
  • list - List available plugins.
  • list-platforms - Lists the available plugin platforms from the registry.
  • list-versions - List versions for a plugin from the registry.
  • update - Update a plugin in the plugin registry.
  • upload-version - Upload a new version of a plugin to the plugin registry.

Plugins are extensible actions executed within pipeline tasks. They can be installed from the plugin registry or uploaded directly with versioned platform-specific binaries.

plugin create subcommand​

Create a new plugin in the plugin registry.

Creates a new plugin at the specified organization. The plugin will be private by default.

phobos plugin create \
  -org-name "<org_name>" \
  -private=true \
  -json \
  <name>

Options​

if-not-exists​

Create the plugin only if it does not exist.
Default: false

json​

Show final output as JSON.

org-name *​

Name of parent organization for the new plugin.

private​

Keep the plugin private i.e. not visible to other organizations.
Default: true

repository-url​

URL of the repository containing the plugin source code.

plugin delete subcommand​

Delete a plugin from the plugin registry.

Permanently removes a plugin and all its versions from the registry.

phobos plugin delete <id>

Options​

version​

Optimistic locking version. Usually not required.

plugin delete-platform subcommand​

Delete a plugin platform from the plugin registry.

Removes a platform binary from a plugin version in the registry.

phobos plugin delete-platform <id>

Options​

version​

Optimistic locking version. Usually not required.

plugin delete-version subcommand​

Delete a plugin version from the plugin registry.

Removes a specific version of a plugin from the registry, including all its platform binaries.

phobos plugin delete-version <id>

Options​

version​

Optimistic locking version. Usually not required.

plugin get subcommand​

Retrieve a plugin from the plugin registry.

Retrieves details about a plugin, including its visibility, organization, and repository URL.

phobos plugin get \
  -json \
  <id>

Options​

json​

Show final output as JSON.

plugin get-platform subcommand​

Retrieve a plugin platform from the plugin registry.

Retrieves details about a specific platform binary for a plugin version.

phobos plugin get-platform <id>

Options​

json​

Show final output as JSON.

plugin get-version subcommand​

Retrieve a plugin version from the plugin registry.

Retrieves details about a specific version of a plugin, including its protocols and checksums.

phobos plugin get-version <id>

Options​

json​

Show final output as JSON.

plugin install subcommand​

Install a plugin from a remote registry.

Installs a plugin from a remote registry.

Plugin will be installed to the user's home directory:

'~/.phobos.d/plugins/'

The plugin source format must be:

'<registry-hostname>/<organization-name>/<plugin-name>'

The registry hostname may be omitted when using the Phobos instance associated with the current profile. An authentication token (if exists) from the current profile will be automatically supplied in the request.

Version constraints can optionally be used to limit the Plugin's versions. The latest version of the plugin (matching the constraints, if supplied) will be used.

phobos plugin install <org_name>/<plugin_name>

Options​

token​

An authentication token to use when downloading plugin from the remote registry. If nothing is supplied, the current profile's token is used when connecting to its endpoint.

version​

Version constraints to adhere to. Installs the latest version of the plugin (matching the constraints, if supplied).

plugin launch subcommand​

Launch a built-in plugin.

Launches built-in plugins. These plugins are not meant to be invoked directly but only by programs which consume them.

plugin list subcommand​

List available plugins.

Lists the available plugins from the plugin registry or built-in plugins.

phobos plugin list \
  -limit 10 \
  -sort-by "UPDATED_AT_DESC" \
  -org-name "<org_name>" \
  -json

Options​

built-in​

List only built-in plugins.
Default: false
Conflicts: org-name, search, cursor, limit, sort-by

cursor​

Cursor string for manual pagination. Not applicable for built-in plugins.
Conflicts: built-in

json​

Show final output as JSON.

limit​

Maximum number of result elements to return. Not applicable for built-in plugins.
Default: 100
Conflicts: built-in

org-name​

Organization name to filter by. Not applicable for built-in plugins.
Conflicts: built-in

search​

Filter to only plugins with this name prefix. Not applicable for built-in plugins.
Conflicts: built-in

sort-by​

Sort by this field.
Values: NAME_ASC, NAME_DESC, UPDATED_AT_ASC, UPDATED_AT_DESC
Conflicts: sort-order, built-in

sort-order !​

Sort in this direction. Not applicable for built-in plugins.
Values: ASC, DESC
Deprecated: use -sort-by
Conflicts: sort-by

plugin list-platforms subcommand​

Lists the available plugin platforms from the registry.

Lists platform binaries available for a plugin version with optional filtering by OS or architecture.

phobos plugin list-platforms \
  -limit 10 \
  -sort-by "UPDATED_AT_DESC" \
  -json \
  -version-id "<plugin_version_id>"

Options​

arch​

Architecture of the platform.

cursor​

Cursor string for manual pagination.

has-binary​

Filter platforms with binary uploaded.

json​

Show final output as JSON.

limit​

Maximum number of result elements to return.
Default: 100

os​

Operating system of the platform.

plugin-id​

ID of the plugin.

sort-by​

Sort by this field.
Values: UPDATED_AT_ASC, UPDATED_AT_DESC
Conflicts: sort-order

sort-order !​

Sort in this direction.
Values: ASC, DESC
Deprecated: use -sort-by
Conflicts: sort-by

version-id​

ID of the plugin version.

plugin list-versions subcommand​

List versions for a plugin from the registry.

Lists all published versions for a plugin with optional filtering by checksums or protocols.

phobos plugin list-versions \
  -limit 10 \
  -sort-by "UPDATED_AT_DESC" \
  -json \
  <plugin_id>

Options​

cursor​

Cursor string for manual pagination.

has-checksums​

Filter by whether the sha sums are uploaded.

json​

Show final output as JSON.

latest​

Filter by whether the version is the latest.

limit​

Maximum number of result elements to return.
Default: 100

sort-by​

Sort by this field.
Values: CREATED_AT_ASC, CREATED_AT_DESC, UPDATED_AT_ASC, UPDATED_AT_DESC
Conflicts: sort-order

sort-order !​

Sort in this direction.
Values: ASC, DESC
Deprecated: use -sort-by
Conflicts: sort-by

version​

Semantic version of the plugin.

plugin update subcommand​

Update a plugin in the plugin registry.

Modifies a plugin's settings such as its repository URL or visibility.

phobos plugin update \
  -private=false \
  <id>

Options​

json​

Show final output as JSON.

private​

Keep the plugin private i.e. not visible to other organizations.

repository-url​

URL of the repository containing the plugin source code.

version​

Optimistic locking version. Usually not required.

plugin upload-version subcommand​

Upload a new version of a plugin to the plugin registry.

Packages and uploads a new version of a plugin, including platform binaries, checksums, and schema.

phobos plugin upload-version \
  -directory "<directory>" \
  <plugin_id>

Options​

directory​

Directory containing the plugin to upload.
Default: .

project command​

Manage projects.

Subcommands:

  • create - Create a project.
  • delete - Delete a project.
  • get - Retrieve a project.
  • list - Retrieve a paginated list of projects.
  • update - Update a project.
  • variable-set - Manage project variable sets.

Projects belong to an organization and provide the resources necessary to deploy an application, including releases, pipelines, and variables.

project create subcommand​

Create a project.

Creates a new project with the given name and description under the specified parent organization.

phobos project create \
  -json \
  -description "<description>" \
  -org-name "<organization_name>" \
  <name>

Options​

description​

Description for the new project.

json​

Show final output as JSON.

org-name *​

Name of parent organization for the new project.

project delete subcommand​

Delete a project.

Permanently removes a project and all its releases, pipelines, and variables.

phobos project delete \
  prn:project:<organization_name>/<project_name>

Options​

version​

Optimistic locking version. Usually not required.

project get subcommand​

Retrieve a project.

Retrieves details about a project by ID.

phobos project get \
  prn:project:<organization_name>/<project_name>

Options​

json​

Show final output as JSON.

project list subcommand​

Retrieve a paginated list of projects.

Lists projects. Supports pagination, filtering and sorting the output.

phobos project list \
  -search "<search_term>" \
  -limit 5 \
  -json

Options​

cursor​

The cursor string for manual pagination.

json​

Show final output as JSON.

limit​

Maximum number of result elements to return.
Default: 100

search​

Filter to only projects with this name prefix.

sort-by​

Sort by this field.
Values: UPDATED_AT_ASC, UPDATED_AT_DESC
Conflicts: sort-order

sort-order !​

Sort in this direction.
Values: ASC, DESC
Deprecated: use -sort-by
Conflicts: sort-by

project update subcommand​

Update a project.

Modifies a project's description.

phobos project update \
  -description "<description>" \
  prn:project:<organization_name>/<project_name>

Options​

description​

Description for the new project.

json​

Show final output as JSON.

version​

Optimistic locking version. Usually not required.

project variable-set subcommand​

Manage project variable sets.

Subcommands:

  • create - Create a new project variable set from a file.
  • get - Get a project variable set revision.
  • list - List project variable set revisions.

Variable sets are versioned collections of variables used to configure pipeline executions. They allow reusing the same pipeline template with different values.

project variable-set create subcommand​

Create a new project variable set from a file.

Creates a new variable set revision for a project by reading variable definitions from a file. The command supports JSON, YAML, and HCL file formats.

Each time this command is run, a new variable set revision is created with all variables replaced by those in the input file. If no variable set exists for the project, a new one will be created with revision "1".

The input file must contain an array of variable objects. Each variable requires the following fields:

  • key: The variable name (required for all variables)
  • value: The variable value (required for all variables) Can be a simple string or a complex type (object, array, number, boolean) Complex types will be automatically serialized to JSON strings
  • pipeline_type: Either "runbook" or "deployment" (required for all variables)
  • environment_scope: The environment context (optional for deployment variables) Examples: "dev", "prod", "" (wildcard for all environments) Defaults to "" if not specified for deployment variables

Note: Runbook variables do not use environment_scope and should not include it. Deployment variables can optionally specify environment_scope (defaults to "*").

Validation Rules:

  • Maximum 1500 variables per variable set
  • Pipeline type must be either "runbook" or "deployment"
  • Deployment variables default to environment_scope "*" if not specified
  • Runbook variables must not include environment_scope
  • No duplicate deployment variables (same key and environment_scope)
  • No duplicate runbook variables (same key)
  • No environment scope conflicts for deployment variables

JSON Format

{
  "variables": [
    {
      "key": "database_url",
      "value": "postgres://localhost:5432/mydb",
      "environment_scope": "dev",
      "pipeline_type": "deployment"
    },
    {
      "key": "api_key",
      "value": "secret-key-value",
      "pipeline_type": "runbook"
    },
    {
      "key": "config",
      "value": {
        "timeout": 30,
        "retries": 3,
        "endpoints": ["api1.example.com", "api2.example.com"]
      },
      "environment_scope": "prod",
      "pipeline_type": "deployment"
    }
  ]
}

YAML Format

variables:
  - key: database_url
    value: postgres://localhost:5432/mydb
    environment_scope: dev
    pipeline_type: deployment
  - key: api_key
    value: secret-key-value
    pipeline_type: runbook
  - key: config
    value:
      timeout: 30
      retries: 3
      endpoints:
        - api1.example.com
        - api2.example.com
    environment_scope: prod
    pipeline_type: deployment

HCL Format

variable "database_url" {
  value              = "postgres://localhost:5432/mydb"
  environment_scope  = "dev"
  pipeline_type      = "deployment"
}

variable "api_key" {
  value         = "secret-key-value"
  pipeline_type = "runbook"
}

variable "config" {
  value = {
    timeout   = 30
    retries   = 3
    endpoints = ["api1.example.com", "api2.example.com"]
  }
  environment_scope = "prod"
  pipeline_type     = "deployment"
}

variable "allowed_ips" {
  value             = ["192.168.1.1", "192.168.1.2", "10.0.0.0/8"]
  environment_scope = "staging"
  pipeline_type     = "deployment"
}

variable "max_connections" {
  value             = 100
  environment_scope = "*"
  pipeline_type     = "deployment"
}

variable "debug_mode" {
  value         = true
  pipeline_type = "runbook"
}
# Create a variable set from a JSON file
phobos project variable-set create \
  -org-name "<org_name>" \
  -project-name "<project_name>" \
  -filename "variables.json"

# Create a variable set from a YAML file in a specific directory
phobos project variable-set create \
  -org-name "<org_name>" \
  -project-name "<project_name>" \
  -directory "./config" \
  -filename "variables.yaml"

# Create a variable set from an HCL file
phobos project variable-set create \
  -org-name "<org_name>" \
  -project-name "<project_name>" \
  -filename "variables.hcl"

# Create a variable set with JSON output
phobos project variable-set create \
  -org-name "<org_name>" \
  -project-name "<project_name>" \
  -filename "variables.json" \
  -json

Options​

directory​

Path to directory containing the variable set file.
Default: .

filename *​

Name of the variable set file (JSON, YAML, or HCL).

json​

Show final output as JSON.

org-name *​

Name of the organization containing the project.

project-name *​

Name of the project to update.

project variable-set get subcommand​

Get a project variable set revision.

Retrieves a specific variable set revision for a project. If no revision is specified, the latest revision is retrieved.

By default, the variables are output in HCL format to stdout. This format matches the input format used by the create command.

Use the -format flag to specify output format: hcl, json, or yaml. Use the -output-file flag to save the variables to a file instead of printing to stdout.

# Get the latest variable set (output to stdout in HCL format)
phobos project variable-set get \
  -org-name "<org_name>" \
  -project-name "<project_name>"

# Get a specific revision
phobos project variable-set get \
  -org-name "<org_name>" \
  -project-name "<project_name>" \
  -revision "<revision>"

# Save to a file
phobos project variable-set get \
  -org-name "<org_name>" \
  -project-name "<project_name>" \
  -output-file "variables.hcl"

# Get as JSON
phobos project variable-set get \
  -org-name "<org_name>" \
  -project-name "<project_name>" \
  -format "json"

# Get as YAML
phobos project variable-set get \
  -org-name "<org_name>" \
  -project-name "<project_name>" \
  -format "yaml"

Options​

format​

Output format: hcl, json, or yaml.
Values: hcl, json, yaml
Default: hcl

org-name *​

Name of the organization containing the project.

output-file​

File path to save the variable set. If not specified, outputs to stdout.

project-name *​

Name of the project.

revision​

Specific revision to retrieve. If not specified, retrieves the latest revision.

project variable-set list subcommand​

List project variable set revisions.

Lists all variable set revisions for a project. Each revision represents a snapshot of the project's variables at a specific point in time.

The list shows the revision number, whether it's the latest revision, when it was created, and the project it belongs to.

# List variable set revisions for a project
phobos project variable-set list \
  -org-name "<org_name>" \
  -project-name "<project_name>"

# List with JSON output
phobos project variable-set list \
  -org-name "<org_name>" \
  -project-name "<project_name>" \
  -json

# List with pagination
phobos project variable-set list \
  -org-name "<org_name>" \
  -project-name "<project_name>" \
  -limit 10 \
  -cursor "<cursor>"

Options​

cursor​

The cursor string for manual pagination.

json​

Show output as JSON.

limit​

Maximum number of variable sets to return.
Default: 100

org-name *​

Name of the organization containing the project.

project-name *​

Name of the project.

release command​

Manage releases and deployments.

Subcommands:

A release is a versioned, packaged snapshot of your project for deployment, containing assets, automation templates, and variables.

release add-participant subcommand​

Add a participant to a release.

Grants a user or team visibility and access to a release.

phobos release add-participant \
  -user-id "<user_id>" \
  <release_id>

Options​

json​

Show final output as JSON.

team-id​

ID of the team to add as a participant to the release.
Conflicts: user-id

user-id​

ID of the user to add as a participant to the release.
Conflicts: team-id

release create subcommand​

Create a release.

Creates a new release for the specified project. The release is defined in a JSON input file. See the example for the expected schema.

Schema for the release JSON input file

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "project_id": {
            "description": "The project ID or PRN",
            "type": "string"
        },
        "lifecycle_id": {
            "description": "The release lifecycle ID or PRN",
            "type": "string"
        },
        "semantic_version": {
            "description": "The semantic version of the release",
            "type": "string"
        },
        "deployment_templates": {
            "description": "The deployment templates to be used for the release",
            "type": "array",
            "minItems": 1,
            "items": {
                "type": "object",
                "properties": {
                    "environment_name": {
                        "description": "The name of the environment",
                        "type": "string"
                    },
                    "pipeline_template_id": {
                        "description": "The ID or PRN of the pipeline template",
                        "type": "string"
                    }
                },
                "required": [
                    "environment_name",
                    "pipeline_template_id"
                ]
            }
        },
        "hcl_variables": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "environment_name": {
                        "description": "The name of the environment (optional - omit to apply to all environments)",
                        "type": "string"
                    },
                    "key": {
                        "description": "The key of the variable",
                        "type": "string"
                    },
                    "value": {
                        "description": "The value of the variable",
                        "type": "string"
                    }
                },
                "required": [
                    "key",
                    "value"
                ]
            }
        },
        "variable_set_revision": {
            "description": "The variable set revision ID or latest",
            "type": "string"
        },
        "due_date": {
            "description": "The due date of the release",
            "type": "string"
        },
        "user_participant_ids": {
            "description": "The user participant IDs or PRNs",
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "team_participant_ids": {
            "description": "The team participant IDs or PRNs",
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "notes": {
            "description": "The notes for the release",
            "type": "string"
        }
    },
    "required": [
        "project_id",
        "lifecycle_id",
        "semantic_version",
        "deployment_templates",
        "hcl_variables",
        "user_participant_ids",
        "team_participant_ids",
        "notes"
    ]
}

Sample release.json

{
    "project_id": "prn:project:<org_name>/<project_name>",
    "lifecycle_id": "prn:release_lifecycle:<org_name>/<lifecycle_name>",
    "semantic_version": "<version>",
    "deployment_templates": [
        {
            "environment_name": "<environment_name>",
            "pipeline_template_id": "prn:pipeline_template:<org_name>/<project_name>/<template_name>/<template_version>"
        }
    ],
    "hcl_variables": [
        {
            "environment_name": "<environment_name>",
            "key": "<key>",
            "value": "<value>"
        },
        {
            "key": "<key>",
            "value": "<value>"
        }
    ],
    "variable_set_revision": "latest",
    "due_date": "2025-01-01T12:00:00.00Z",
    "user_participant_ids": [
        "prn:user:<username>"
    ],
    "team_participant_ids": [],
    "notes": "<notes>"
}
phobos release create -filename "release.json"

Options​

directory​

Path to the directory that contains the release JSON input file.
Default: .

filename​

Name of the JSON input file.
Default: release.json

json​

Show final output as JSON.

release delete subcommand​

Delete a release.

Permanently removes a release and its associated deployments.

phobos release delete <id>

Options​

version​

Optimistic locking version. Usually not required.

release get subcommand​

Get a release.

Retrieves details about a release, including its version, status, and deployment information.

phobos release get \
  -json \
  <id>

Options​

json​

Show final output as JSON.

release list subcommand​

Retrieve a paginated list of releases.

Lists releases. Supports pagination, filtering and sorting the output.

phobos release list \
  -limit 5 \
  -org-name "<org_name>" \
  -project-name "<project_name>" \
  -json

Options​

cursor​

Cursor string for manual pagination.

json​

Show final output as JSON.

limit​

Maximum number of results to return.
Default: 100

org-name *​

The organization to limit search.

project-name *​

The project to limit search.

sort-by​

Sort by this field.
Values: CREATED_AT_ASC, CREATED_AT_DESC, UPDATED_AT_ASC, UPDATED_AT_DESC
Conflicts: sort-order

sort-order !​

Sort in this direction.
Values: ASC, DESC
Deprecated: use -sort-by
Conflicts: sort-by

release remove-participant subcommand​

Remove a participant from a release.

Revokes a user or team's access to a release.

phobos release remove-participant \
  -user-id "<user_id>" \
  <release_id>

Options​

json​

Show final output as JSON.

team-id​

ID of the team participant to remove from the release.
Conflicts: user-id

user-id​

ID of the user participant to remove from the release.
Conflicts: team-id

release update subcommand​

Update a release.

Modifies release properties such as notes or due date.

phobos release update \
  -due-date "none" \
  -notes "this is a note" \
  <id>

Options​

due-date​

Due date for the release. Format must be RFC3339. Supplying 'none' will remove the due date.

json​

Show final output as JSON.

notes​

Notes associated with the release.

release update-deployment subcommand​

Update a release deployment.

Updates the deployment configuration for a release using a new input file.

phobos release update-deployment \
  -filename "my-deployment.json" \
  <release_id>

Options​

directory​

Path to the directory that contains the deployment JSON input file.
Default: .

filename​

Name of the JSON input file.
Default: deployment.json

json​

Show final output as JSON.

release-lifecycle command​

Manage release lifecycles.

Subcommands:

  • create - Create a release lifecycle.
  • delete - Delete a release lifecycle.
  • get - Retrieve a release lifecycle.
  • list - Retrieve a paginated list of release lifecycles.
  • update - Update a release lifecycle with a new lifecycle template.
  • validate - Validate a release lifecycle template.

Release lifecycles define how releases propagate between environments through sequential stages with deployment targets, approvals, and gates.

release-lifecycle create subcommand​

Create a release lifecycle.

Creates a new release lifecycle under the specified organization.

phobos release-lifecycle create \
  -filename "<filename>" \
  -org-name "<org_name>" \
  -project-name "<project_name>" \
  <name>

Options​

directory​

Path to directory that contains the HCL input file.
Default: .

filename​

Name of HCL input file.
Default: lifecycle.hcl

json​

Show final output as JSON.

org-name *​

Name of the organization.

project-name​

Name of the project.

release-lifecycle delete subcommand​

Delete a release lifecycle.

Permanently removes a release lifecycle.

phobos release-lifecycle delete <id>

Options​

version​

Optimistic locking version. Usually not required.

release-lifecycle get subcommand​

Retrieve a release lifecycle.

Retrieves details about a release lifecycle by ID.

phobos release-lifecycle get \
  -json \
  <id>

Options​

json​

Show final output as JSON.

release-lifecycle list subcommand​

Retrieve a paginated list of release lifecycles.

Lists release lifecycles. Supports pagination, filtering and sorting the output.

phobos release-lifecycle list \
  -limit 5 \
  -org-name "<org_name>" \
  -json

Options​

cursor​

The cursor string for manual pagination.

json​

Show final output as JSON.

limit​

Maximum number of result elements to return.
Default: 100

org-name *​

The organization to limit search.

project-name​

Name of the project to filter by.

scope ...​

Scope to filter release lifecycles.
Values: GLOBAL, ORGANIZATION, PROJECT

search​

Filter to only release lifecycles with this name prefix.

sort-by​

Sort by this field.
Values: UPDATED_AT_ASC, UPDATED_AT_DESC
Conflicts: sort-order

sort-order !​

Sort in this direction.
Values: ASC, DESC
Deprecated: use -sort-by
Conflicts: sort-by

release-lifecycle update subcommand​

Update a release lifecycle with a new lifecycle template.

Replaces the lifecycle template associated with a release lifecycle.

phobos release-lifecycle update \
  -filename "<filename>" \
  <id>

Options​

directory​

Path to directory that contains the HCL input file.
Default: .

filename​

Name of HCL input file.
Default: lifecycle.hcl

json​

Show final output as JSON.

release-lifecycle validate subcommand​

Validate a release lifecycle template.

Checks a release lifecycle template for errors without creating or updating any resources.

phobos release-lifecycle validate \
  -filename "<filename>"

Options​

directory​

Path to directory that contains the HCL input file.
Default: .

filename​

Name of HCL input file.
Default: lifecycle.hcl

sso command​

Authenticate with the OAuth2 provider.

Subcommands:

  • login - Log in to the OAuth2 provider and return an authentication token.

The sso command authenticates the CLI with the OAuth2 provider and stores a token for subsequent authenticated requests. Required before running any command that interacts with the Phobos API.

sso login subcommand​

Log in to the OAuth2 provider and return an authentication token.

Starts an embedded web server and opens a browser to the OAuth2 provider's login page. If SSO is active, the user is signed in automatically. The authentication token is captured and stored for use in subsequent commands.

phobos sso login

version command​

Get the CLI's version.

Displays the current CLI version and checks for available updates.

phobos version -json

Options​

json​

Show final output as JSON.
Default: false

Frequently asked questions (FAQ)​

Is configuring a profile necessary?​

By default, the CLI will use the default Phobos endpoint passed in at build-time. Unless a different endpoint is needed, no profile configuration is necessary. Simply run phobos sso login and the default profile will be created and stored in the settings file.

How do I use profiles?​

The profile can be specified using the -p global flag or the PHOBOS_PROFILE environment variable. The flag must come before a command name. For example, phobos -p local organization list will list all the organizations using the Phobos endpoint in the local profile. Service accounts can use profiles in the same manner as human users.

Where are the settings and credentials files located?​

The settings file is located at ~/.phobos/settings.json and contains profile configuration (endpoints, options). Credentials are stored separately in ~/.phobos/credentials.json so they can have stricter permissions.

caution

Never share the credentials file as it contains sensitive data like the authentication token from SSO!

How do I disable colored output?​

Set the NO_COLOR environment variable to any value to disable colored output. For example, NO_COLOR=1 phobos organization list.