LinchPin Command-Line API

The linchpin.cli module provides an API for writing a command-line interface, the LinchPin Command Line Shell implementation being the reference implementation.

class linchpin.cli.LinchpinCli(ctx)[source]
find_include(filename, ftype='topology')[source]

Find the included file to be acted upon.

  • filename – name of file from to be loaded
  • ftype – the file type to locate: topology, layout (default: topology)
lp_destroy(targets=(), run_id=None, tx_id=None)[source]

This function takes a list of targets, and performs a destructive teardown, including undefining nodes, according to the target(s).

See also

lp_down - currently unimplemented

  • targets – A tuple of targets to destroy.
  • run_id – An optional run_id to use
  • tx_id – An optional tx_id to use
lp_down(pinfile, targets=(), run_id=None)[source]

This function takes a list of targets, and performs a shutdown on nodes in the target’s topology. Only providers which support shutdown from their API (Ansible) will support this option.


See also


  • pinfile – Provided PinFile, with available targets,
  • targets – A tuple of targets to provision.
lp_fetch(src, root='', fetch_type='workspace', fetch_protocol=None, fetch_ref=None, dest_ws=None, nocache=False)[source]

Fetch a workspace from git, http(s), or a local directory, and generate a provided workspace

  • src – The URL or URI of the remote directory
  • root – Used to specify the location of the workspace within the remote. If root is not set, the root of the given remote will be used.
  • fetch_type – Specifies which component(s) of a workspace the user wants to fetch. Types include: topology, layout, resources, hooks, workspace. (default: workspace)
  • fetch_protocol – The protocol to use to fetch the workspace. (default: git)
  • fetch_ref – Specify the git branch. Used only with git protocol (eg. master). If not used, the default branch will be used.
  • dest_ws

    Workspaces destination, the workspace will be relative to this location.

    If dest_ws is not provided and -r/–root is provided, the basename will be the name of the workspace within the destination. If no root is provided, a random workspace name will be generated. The destination can also be explicitly set by using -w (see linchpin –help).

  • nocache – If true, don’t copy from the cache dir, unless it’s longer than the configured fetch.cache_days (1 day) (default: False)

Initializes a linchpin project. Creates the necessary directory structure, includes PinFile, topologies and layouts for the given provider. (Default: Dummy. Other providers not yet implemented.)

Parameters:providers – A list of providers for which templates

(and a target) will be provided into the workspace. NOT YET IMPLEMENTED

lp_up(targets=(), run_id=None, tx_id=None, inv_f='cfg')[source]

This function takes a list of targets, and provisions them according to their topology.

  • targets – A tuple of targets to provision
  • run_id – An optional run_id if the task is idempotent
  • tx_id – An optional tx_id if the task is idempotent
lp_validate(targets=(), old_schema=False)[source]

This function takes a list of targets, and validates their topology.

Parameters:targets – A tuple of targets to provision
:param old_schema
Denotes whether schema should be validated with the old schema rather than the new one!/usr/bin/env python

getter for pinfile template data


getter function for pinfile name


getter function for context workspace

class linchpin.cli.context.LinchpinCliContext[source]

Context object, which will be used to manage the cli, and load the configuration file


Update self.cfgs from the linchpin configuration file (linchpin.conf).

The following paths are used to find the config file. The search path defaults to the first-found order:

* /etc/linchpin.conf
* /linchpin/library/path/linchpin.conf
* <workspace>/linchpin.conf

An alternate search_path can be passed.

Parameters:search_path – A list of paths to search a linchpin config

(default: None)

log(msg, **kwargs)[source]

Logs a message to a logfile or the console

  • msg – message to log
  • lvl – keyword argument defining the log level
  • msg_type – keyword argument giving more flexibility.


Only msg_type STATE is currently implemented.


Logs a DEBUG message


Logs an INFO message


Logs a message to stdout


getter function for pinfile name


Setup logging to a file, console, or both. Modifying the linchpin.conf appropriately will provide functionality.


getter function for workspace