Command Line

unfurl
- Deploy Commands
  - check
  - deploy
  - discover
  - plan
  - run
  - stop
  - teardown
- Project Commands
  - clone
  - commit
  - git
  - git-status
  - init
- Utility Commands
  - cloudmap
  - export
  - home
  - runtime
  - serve
- Info Commands
  - help
  - status
  - validate
  - version

unfurl 

unfurl [OPTIONS] COMMAND [ARGS]...

Options

--skip-upstream-check: Skip pulling latest upstream changes from existing repositories.

--no-version-check: Skip the Unfurl version check when invoking the runtime.

--version-check <version_check>: Abort if the runtime’s Unfurl is older than the given version

--loglevel <loglevel>: One of trace debug verbose warning info error critical (overrides -v)

--tmp <tmp>: Directory for saving temporary files

--logfile <logfile>: Log messages to file (at DEBUG level)

-q, --quiet: Only output critical errors to the stdout

-v, --verbose: Verbose mode (-vv or -vvv for more)

--no-runtime: Ignore runtime settings

--runtime <runtime>: Use the given runtime

--home <home>: Path to .unfurl_home (Use ‘’ to ignore default home)

Environment variables

UNFURL_SKIP_UPSTREAM_CHECK: Provide a default for --skip-upstream-check

UNFURL_VERSION_CHECK: Provide a default for --version-check

UNFURL_LOGGING: Provide a default for --loglevel

UNFURL_TMPDIR: Provide a default for --tmp

UNFURL_LOGFILE: Provide a default for --logfile

UNFURL_NORUNTIME: Provide a default for --no-runtime

UNFURL_RUNTIME: Provide a default for --runtime

UNFURL_HOME: Provide a default for --home

Deploy Commands 

See Jobs and Workflows.

check 

Check and update the status of the ensemble’s instances

unfurl check [OPTIONS] [ENSEMBLE]

Options

--force: (Re)run operation regardless of instance’s status or state

--template <template>: TOSCA template to target.

--var <NAME VALUE>: name/value pair to pass to job (multiple times ok).

--use-environment <NAME>: Run this job in the given environment.

--starttime <starttime>: Set the start time of the job.

--instance <instance>: Instance name to target (multiple times ok).

--output <output>

How to print summary of job run

Options: text | json | none

--trace <trace>: Set the query’s trace level

--query <query>: Run the given expression upon job completion

--change-detection <change_detection>

How to detect configuration changes to existing instances. (Default: evaluate)

Options: skip | always | evaluate

--skip-new: Don’t create instance for new templates.

--jobexitcode <jobexitcode>

Set exit code to 64 if job ends at given status. (Default: never)

Options: error | degraded | never

-m, --message <message>: commit message to use

--dirty <dirty>

When there are uncommitted changes before run. (Default: auto)

Options: abort | ok | auto

--push: Push after committing. (Default: false)

--commit: Commit modified files to the ensemble repository. (Default: false)

--dryrun: Do not modify anything, just do a dry run.

Arguments

ENSEMBLE: Optional argument

deploy 

Deploy the given ensemble

unfurl deploy [OPTIONS] [ENSEMBLE]

Options

--force: (Re)run operation regardless of instance’s status or state

--template <template>: TOSCA template to target.

--var <NAME VALUE>: name/value pair to pass to job (multiple times ok).

--use-environment <NAME>: Run this job in the given environment.

--starttime <starttime>: Set the start time of the job.

--instance <instance>: Instance name to target (multiple times ok).

--output <output>

How to print summary of job run

Options: text | json | none

--trace <trace>: Set the query’s trace level

--query <query>: Run the given expression upon job completion

--check: check if new instances exist before deploying

--destroyunmanaged: include unmanaged instances for consideration when destroying

--prune: Destroy instances that are no longer used

--upgrade: Apply major versions changes.

--repair <repair>

Re-run operations on instances that are in an error or degraded state. (Default: error)

Options: error | degraded | none

--change-detection <change_detection>

How to detect configuration changes to existing instances. (Default: evaluate)

Options: skip | always | evaluate

--skip-new: Don’t create instance for new templates.

-a, --approve: Don’t prompt for approval to apply changes.

--jobexitcode <jobexitcode>

Set exit code to 64 if job ends at given status. (Default: never)

Options: error | degraded | never

-m, --message <message>: commit message to use

--dirty <dirty>

When there are uncommitted changes before run. (Default: auto)

Options: abort | ok | auto

--push: Push after committing. (Default: false)

--commit: Commit modified files to the ensemble repository. (Default: false)

--dryrun: Do not modify anything, just do a dry run.

Arguments

ENSEMBLE: Optional argument

Environment variables

UNFURL_APPROVE: Provide a default for -a

discover 

Run the “discover” workflow which updates the ensemble’s spec by probing its live instances.

unfurl discover [OPTIONS] [ENSEMBLE]

Options

--force: (Re)run operation regardless of instance’s status or state

--template <template>: TOSCA template to target.

--var <NAME VALUE>: name/value pair to pass to job (multiple times ok).

--use-environment <NAME>: Run this job in the given environment.

--starttime <starttime>: Set the start time of the job.

--instance <instance>: Instance name to target (multiple times ok).

--output <output>

How to print summary of job run

Options: text | json | none

--trace <trace>: Set the query’s trace level

--query <query>: Run the given expression upon job completion

-a, --approve: Don’t prompt for approval to apply changes.

--jobexitcode <jobexitcode>

Set exit code to 64 if job ends at given status. (Default: never)

Options: error | degraded | never

-m, --message <message>: commit message to use

--dirty <dirty>

When there are uncommitted changes before run. (Default: auto)

Options: abort | ok | auto

--push: Push after committing. (Default: false)

--commit: Commit modified files to the ensemble repository. (Default: false)

--dryrun: Do not modify anything, just do a dry run.

Arguments

ENSEMBLE: Optional argument

Environment variables

UNFURL_APPROVE: Provide a default for -a

plan 

Print the given deployment plan

unfurl plan [OPTIONS] [ENSEMBLE]

Options

--force: (Re)run operation regardless of instance’s status or state

--template <template>: TOSCA template to target.

--var <NAME VALUE>: name/value pair to pass to job (multiple times ok).

--use-environment <NAME>: Run this job in the given environment.

--starttime <starttime>: Set the start time of the job.

--instance <instance>: Instance name to target (multiple times ok).

--output <output>

How to print summary of job run

Options: text | json | none

--trace <trace>: Set the query’s trace level

--query <query>: Run the given expression upon job completion

--check: check if new instances exist before deploying

--destroyunmanaged: include unmanaged instances for consideration when destroying

--prune: Destroy instances that are no longer used

--upgrade: Apply major versions changes.

--repair <repair>

Re-run operations on instances that are in an error or degraded state. (Default: error)

Options: error | degraded | none

--change-detection <change_detection>

How to detect configuration changes to existing instances. (Default: evaluate)

Options: skip | always | evaluate

--skip-new: Don’t create instance for new templates.

--workflow <workflow>: plan workflow (default: deploy)

Arguments

ENSEMBLE: Optional argument

run 

Run a TOSCA operation or an ad-hoc shell command in the context of the given ensemble. Use “–” to separate the given command line, for example:

> unfurl run – echo ‘hello!’

If –host or –module is set, the ansible configurator will be used. e.g.:

> unfurl run –host=example.com – echo ‘hello!’

unfurl run [OPTIONS] [CMDLINE]...

Options

--ensemble <ensemble>

--save: Save in job history.

-a, --approve: Don’t prompt for approval to apply changes.

--jobexitcode <jobexitcode>

Set exit code to 64 if job ends at given status. (Default: never)

Options: error | degraded | never

-m, --message <message>: commit message to use

--dirty <dirty>

When there are uncommitted changes before run. (Default: auto)

Options: abort | ok | auto

--push: Push after committing. (Default: false)

--commit: Commit modified files to the ensemble repository. (Default: false)

--dryrun: Do not modify anything, just do a dry run.

--var <NAME VALUE>: name/value pair to pass to job (multiple times ok).

--use-environment <NAME>: Run this job in the given environment.

--starttime <starttime>: Set the start time of the job.

--instance <instance>: Instance name to target (multiple times ok).

--output <output>

How to print summary of job run

Options: text | json | none

--trace <trace>: Set the query’s trace level

--query <query>: Run the given expression upon job completion

--host <host>: Name of instance to run the command on.

--operation <operation>: TOSCA operation to run.

--module <module>: Ansible module to run. (default: command)

Arguments

CMDLINE: Optional argument(s)

Environment variables

UNFURL_APPROVE: Provide a default for -a

stop 

Stop running instances.

unfurl stop [OPTIONS] [ENSEMBLE]

Options

--force: (Re)run operation regardless of instance’s status or state

--template <template>: TOSCA template to target.

--var <NAME VALUE>: name/value pair to pass to job (multiple times ok).

--use-environment <NAME>: Run this job in the given environment.

--starttime <starttime>: Set the start time of the job.

--instance <instance>: Instance name to target (multiple times ok).

--output <output>

How to print summary of job run

Options: text | json | none

--trace <trace>: Set the query’s trace level

--query <query>: Run the given expression upon job completion

-a, --approve: Don’t prompt for approval to apply changes.

--jobexitcode <jobexitcode>

Set exit code to 64 if job ends at given status. (Default: never)

Options: error | degraded | never

-m, --message <message>: commit message to use

--dirty <dirty>

When there are uncommitted changes before run. (Default: auto)

Options: abort | ok | auto

--push: Push after committing. (Default: false)

--commit: Commit modified files to the ensemble repository. (Default: false)

--dryrun: Do not modify anything, just do a dry run.

Arguments

ENSEMBLE: Optional argument

Environment variables

UNFURL_APPROVE: Provide a default for -a

teardown 

Destroy what was previously deployed by running the “undeploy” workflow.

unfurl teardown [OPTIONS] [ENSEMBLE]

Options

--force: (Re)run operation regardless of instance’s status or state

--template <template>: TOSCA template to target.

--var <NAME VALUE>: name/value pair to pass to job (multiple times ok).

--use-environment <NAME>: Run this job in the given environment.

--starttime <starttime>: Set the start time of the job.

--instance <instance>: Instance name to target (multiple times ok).

--output <output>

How to print summary of job run

Options: text | json | none

--trace <trace>: Set the query’s trace level

--query <query>: Run the given expression upon job completion

-a, --approve: Don’t prompt for approval to apply changes.

--jobexitcode <jobexitcode>

Set exit code to 64 if job ends at given status. (Default: never)

Options: error | degraded | never

-m, --message <message>: commit message to use

--dirty <dirty>

When there are uncommitted changes before run. (Default: auto)

Options: abort | ok | auto

--push: Push after committing. (Default: false)

--commit: Commit modified files to the ensemble repository. (Default: false)

--dryrun: Do not modify anything, just do a dry run.

--destroyunmanaged: include unmanaged instances for consideration when destroying

Arguments

ENSEMBLE: Optional argument

Environment variables

UNFURL_APPROVE: Provide a default for -a

Project Commands 

clone 

Create a new ensemble or project from a service template or an existing ensemble or project.

SOURCE Path or git url to a project, ensemble, or service template

DEST Path to the new project or ensemble

unfurl clone [OPTIONS] SOURCE [DEST]

Options

--mono: Don’t create a separate ensemble repository.

--existing: Add project to nearest existing repository.

--empty: Don’t create a new ensemble.

--design: Set up project for blueprint development.

--use-environment <NAME>: Associate the given environment with the ensemble.

--skeleton <NAME or PATH>: Name of built-in skeleton or path to a directory with a project skeleton.

--overwrite: Create ensemble in the given directory even if it exists.

--use-deployment-blueprint <NAME>: Use this deployment blueprint.

--var <NAME VALUE>: Name/value pair to pass to skeleton (multiple times ok).

Arguments

SOURCE: Required argument

DEST: Optional argument

commit 

Commit any changes to the given project or ensemble.

unfurl commit [OPTIONS] [PROJECT_OR_ENSEMBLE_PATH]

Options

-m, --message <message>: commit message to use

--no-edit: Use default message instead of invoking the editor

--skip-add: Don’t add files for committing (user must add using git)

--all-repositories: Commit all repositories the ensemble accesses

--use-environment <NAME>: Use this environment.

Arguments

PROJECT_OR_ENSEMBLE_PATH: Optional argument

git 

unfurl git [git command] [git command arguments]: Run the given git command on each project repository.

unfurl git [OPTIONS] [GITARGS]...

Options

--dir <dir>: Path to project or ensemble (default: “.”)

Arguments

GITARGS: Optional argument(s)

git-status 

Show the git status for paths relevant to the given project or ensemble.

unfurl git-status [OPTIONS] [PROJECT_OR_ENSEMBLE_PATH]

Options

--dirty: Only show repositories with uncommitted changes

--use-environment <NAME>: Use this environment.

Arguments

PROJECT_OR_ENSEMBLE_PATH: Optional argument

init 

Create a new project, or, if [project_dir] is an existing project, create a new ensemble. If [ensemble_name] is omitted, use a default name.

unfurl init [OPTIONS] [PROJECTDIR] [ENSEMBLE_NAME]

Options

--mono: Don’t create a separate ensemble repository.

--existing: Add project to nearest existing repository.

--submodule: Set the ensemble repository as a git submodule.

--empty: Don’t create a default ensemble.

--skeleton <NAME or PATH>: Name of built-in skeleton or path to a directory with a project skeleton.

--var <NAME VALUE>: Name/value pair to pass to skeleton (multiple times ok).

--use-environment <NAME>: Associate the given environment with this ensemble.

--use-deployment-blueprint <NAME>: Use this deployment blueprint.

--as-shared-environment: Create an environment with the same name and set this project as its shared repository.

--shared-repository <shared_repository>: Create the ensemble in an repository outside the project.

--render: Generate files only (don’t commit them).

Arguments

PROJECTDIR: Optional argument

ENSEMBLE_NAME: Optional argument

Utility Commands 

cloudmap 

Manage a cloud map.

[CLOUDMAP] is either a named cloudmap, a git url, or a local path. (Default: “cloudmap”)

unfurl cloudmap [OPTIONS] [CLOUDMAP]

Options

--sync <HOST>: Sync the given repository host (“local”, name, or url).

--import <HOST>: Update the cloudmap with the given repository host (“local”, name, or url).

--export <HOST>: Update the given repository host (“local”, name, or url) with the local repositories recorded in the cloudmap.

--namespace <namespace>: Limit sync to repositories in this folder or group.

--repository <repository>: Limit sync to this one repository (matches key).

--clone-root <clone_root>: Directory to clone repositories to.

--visibility <visibility>

Only filter projects by visibility (overrides config).

Options: public | any

--project <project>: Unfurl project to use. (Default: “.”)

--skip-analysis: Don’t analyze files in repositories

--force: Force push to repository host

--dryrun: Do not modify the repository host, just do a dry run.

Arguments

CLOUDMAP: Optional argument

export 

If path to an Unfurl project or ensemble, export ensemble in a simplified json format or as Python source. If a Python file, export to YAML.

unfurl export [OPTIONS] [PATH]

Options

--format <format>

Default: deployment

Options: python | blueprint | environments | deployment | deployments

--use-environment <NAME>: Export using this environment.

--file <file>: Write json export to this file instead of the console.

--overwrite <overwrite>

Overwrite existing files (Default: auto)

Options: older | never | always | auto

--python-target <python_target>

Python version to target when –format python (Default: current version)

Options: 3.7 | 3.8 | 3.9 | 3.10

Arguments

PATH: Optional argument

Environment variables

UNFURL_OVERWRITE_POLICY: Provide a default for --overwrite

home 

If no options are set, display the location of current unfurl home. To create a new home project use –init and the global –home option.

unfurl home [OPTIONS]

Options

--render: Generate files only (don’t create repository)

--init: Create a new home project

--replace: Replace (and backup) current home project

--skeleton <NAME or PATH>: Name of built-in skeleton or path to a directory with a project skeleton. (Default: home)

--poly: Create a separate repository for the localhost ensemble.

--var <NAME VALUE>: Name/value pair to pass to skeleton (multiple times ok).

runtime 

If no options are set, display the runtime currently used by the project. To create a new runtime in the project root use –init and the global –runtime option.

unfurl runtime [OPTIONS] [PROJECT_FOLDER]

Options

--init: Create a new runtime

--update: Update Python requirements to match this instance of Unfurl.

Arguments

PROJECT_FOLDER: Optional argument

serve 

Run Unfurl’s built-in web server.

unfurl serve [OPTIONS] [PROJECT_OR_ENSEMBLE_PATH]

Options

--port <port>: Port to listen on (default: 8081)

--address <address>: Host to listen on (0.0.0.0 for external connections) (default: localhost)

--secret <secret>: Require secret as Authorization: Bearer <secret> header or “secret” URL parameter.

--clone-root <clone_root>: Where to clone repositories (default: ./repos)

--cloud-server <cloud_server>: Unfurl Cloud server URL to connect to.

--cors <cors>: enable CORS with origin (e.g. “*”)

--gui: Serve the Unfurl GUI app

Arguments

PROJECT_OR_ENSEMBLE_PATH: Optional argument

Environment variables

UNFURL_SERVE_PATH: Provide a default for PROJECT_OR_ENSEMBLE_PATH

UNFURL_SERVE_SECRET: Provide a default for --secret

UNFURL_CLONE_ROOT: Provide a default for --clone-root

UNFURL_CLOUD_SERVER: Provide a default for --cloud-server

UNFURL_SERVE_CORS: Provide a default for --cors

UNFURL_SERVE_GUI: Provide a default for --gui

Info Commands 

help 

Get help on a command.

unfurl help [OPTIONS] [CMD]

Arguments

CMD: Optional argument

status 

Show the status of deployed resources in the given ensemble.

(Use global -v for verbose display.)

unfurl status [OPTIONS] [ENSEMBLE]

Options

--query <query>: Run the given expression

--trace <trace>: Set the query’s trace level

--use-environment <NAME>: Use this environment.

Arguments

ENSEMBLE: Optional argument

validate 

Validate the syntax of the given Unfurl project, ensemble, cloud map, or TOSCA file.

unfurl validate [OPTIONS] [PATH]

Options

--use-environment <NAME>: Use this environment.

--as-template: Treat as an ensemble template.

Arguments

PATH: Optional argument

version 

Print the current version of Unfurl.

unfurl version [OPTIONS]

Options

--semver: Print the released semantic version.

--remote: Also print the version installed in the current runtime.