Triggering Code Manager on the command line

Use the puppet-code command to trigger Code Manager from the command line and deploy your environments.

Installing and configuring puppet-code

Puppet Enterprise (PE) automatically installs and configures the puppet-code command on your primary server as part of the included PE client tools package. You can also set up puppet-code on an agent node or workstation, customize configuration for different users, or change the global configuration settings.

The global configuration settings for *nix and macOS systems are in a JSON file located at: 
/etc/puppetlabs/client-tools/puppet-code.conf
By default, this configuration file contains:
{
"cacert": "/etc/puppetlabs/puppet/ssl/certs/ca.pem",
"token-file": "~/.puppetlabs/token",
"service-url": "https://<PRIMARY_HOSTNAME>:8170/code-manager"
 }

On Windows systems, the global configuration settings are located at:C:\ProgramData\PuppetLabs\client-tools\puppet-code.conf

On Windows, the default configuration file contains:
{
"cacert": "C:\\ProgramData\\PuppetLabs\\puppet\\etc\\ssl\\certs\\ca.pem",
"token-file": "C:\\Users\\<username>\\.puppetlabs\\token",
"service-url": "https://<PRIMARY_HOSTNAME>:8170/code-manager"
 }
Important: On PE-managed machines, Puppet manages this file for you. Don't manually edit this file, because Puppet overwrites your changes the next time it runs.
In addition to the global settings, you can:

When Deploying environments with puppet-code, you can use the default config file, an alternative config file, or config settings supplied directly in the command.

Configuration precedence and puppet-code

There are several ways to configure puppet-code, but some configuration methods take precedence over others.

If no other configuration is specified, puppet-code uses the settings in the global configuration file. User-specific configuration files override the global configuration file.

If you Use a temporary puppet-code.conf file, Puppet temporarily uses that configuration file only. In this case, Puppet doesn't read the global or user-specific configuration files at all for that one deployment.

If you Use a temporary cacert, token-file, or service-url, by specifying individual configuration options directly on the command line, those options temporarily take precedence over any place they are specified in default, global, or user-specific configuration file settings. Settings you don't specify in this way are applied according to their normal configuration precedence.

Deploying environments with puppet-code

Use puppet-code deploy to trigger a Code Manager code deployment.

You must supply a specific environment's name or the --all flag (to deploy all environments). For example:
puppet-code deploy production
puppet-code deploy --all
Without any other options specified, the default puppet-code deploy <ENVIRONMENT_OPTION> command deploys the specified environment(s) and returns only deployment queuing results.

In addition to the options for --wait and custom configuration settings (described below), use the Reference: puppet-code command to learn about other puppet-code options.

Running puppet-code on Windows

When running puppet-code on a managed or non-managed Windows workstation, you must specify the full path to the command. For example:
C:\Program Files\Puppet Labs\Client\bin\puppet code deploy production --wait

For more information about Windows modifications, refer to Using example commands.

Return deployment results (--wait)

If you want puppet-code deploy to return the results of the actual deployment event(s), add the --wait flag. Otherwise, the command returns only deployment queuing information.

For example:
puppet-code deploy --all --wait

With the --wait flag, Code Manager deploys code to the specified environment(s), and only returns results after file sync has deployed code to the live code directory and all compilers.

The resulting message includes the deployment signature, which is the commit SHA from the control repo used to deploy the environment. The output also includes two other SHAs that indicate that file sync is aware that the environment has been newly deployed to the code staging directory.
Note: In deployments that are geographically dispersed or have a large quantity of environments, complete code deployment might take several minutes.

Use a temporary puppet-code.conf file

You can use a custom configuration file to temporary override default, global, and user-specific configuration settings by specifying the temporary file on the command line.

If you want to temporarily override default, global, and user-specific configuration settings, use the --config-file option to specify the file path to an alternative puppet-code.conf file. For example: 
puppet-code --config-file ~/.puppetlabs/myconfigfile/puppet code.conf deploy --all

This configuration file is only used for this one deployment.

Use a temporary cacert, token-file, or service-url

You can temporarily override individual puppet-code configuration settings by specifying individual settings on the command line.

If you want to temporarily override default, global, and user-specific configuration settings, you can specify these settings directly on the command line:
  • --cacert
  • --token-file or -t
  • --service-url
For example, this command uses a custom URL to call the Code Manager service:
puppet-code --service-url "https://puppet.example.com:8170/code-manager" deploy production
Tip: For Windows, macOS, and *nix argument formatting examples, refer to puppet-code configuration settings.

When you specify settings this way, your custom settings are only used for this one deployment. Unspecified settings aren't overridden.

Advanced puppet-code configuration

You can configure the puppet-code command on agent nodes, workstations not managed by PE, and for individual users (on any machine).

Configure puppet-code on agents and workstations

To use puppet-code on an agent node or on a workstation that is not managed by PE, install the client tools package and configure puppet-code on that machine.

Before you begin
Download and install the client tools package.
  1. On the agent node or workstation, create a config file called puppet-code.conf in the client tools directory.
    • For Linux and Mac OS X systems, the default client tools directory is /etc/puppetlabs/client-tools
    • For Windows systems, the default client tools directory is C:\ProgramData\PuppetLabs\client-tools
  2. If this machine is not managed by PE, edit the puppet-code.conf file as needed to customize the cacert, token-file, and service-url settings. These must use proper JSON formatting.
    Important: On PE-managed machines, Puppet manages this file for you. Don't manually edit this file on PE-managed machines, because Puppet overwrites your changes the next time it runs. However, you can apply temporary modifications, or use an alternative config file, when Deploying environments with puppet-code.

Configure puppet-code for different users

On any machine, you can configure puppet-code settings for individual users.

Before you begin
If PE is not installed on the workstation you are configuring, you must Configure puppet-code on the workstation first.
  1. Create a puppet-code.conf file in the user's client tools directory.
    • For Linux or Mac OS X systems, place the file in the user's ~/.puppetlabs/client-tools/ directory.
    • For Windows systems, place the file in the default user config file location at: C:\Users\<username>\.puppetlabs\ssl\certs\ca.pem
  2. In the user's puppet-code.conf file, customize the cacert, token-file, and service-url settings at needed. These must use proper JSON formatting.

Reference: puppet-code command

The puppet-code command accepts options, actions, and deploy action options.

Use the following format to modify the puppet-code command:
puppet-code [GLOBAL_OPTIONS] <ACTION> [ACTION_OPTIONS]

Global puppet-code options

The puppet-code command supports these global options.

Option Description Allowed arguments
--help or -h Prints puppet-code usage information. No arguments supported
--version or -V Prints the application's version. No arguments supported
--log-level or -l Sets the log verbosity. One of the following log levels:
  • none
  • trace
  • debug
  • info
  • warn
  • error
  • fatal
--config-file or -c Specifies a puppet-code.conf file that takes precedence over all other existing puppet-code.conf files.

Refer to: Use a temporary puppet-code.conf file

 A path to a puppet-code.conf file
--cacert Specifies a Puppet CA certificate that overrides the cacert setting in any configuration files.

Refer to: Use a temporary cacert, token-file, or service-url

 A path to the location of the CA Certificate
--token-file or -t Specifies an authentication token that overrides the token-file setting in any configuration files.

Refer to: Use a temporary cacert, token-file, or service-url

 A path to the location of the authentication token
--service-url Specifies a base URL for the Code Manager service, overriding the service-url setting in any configuration files.

Refer to: Use a temporary cacert, token-file, or service-url

 A valid URL to call the Code Manager service

puppet-code actions

The puppet-code command can perform these actions.

Action Description Action options
deploy Triggers the Code Manager service to deploy code.

Refer to: Deploying environments with puppet-code

 Refer to: puppet-code deploy action options
print-config Prints the resolved puppet-code configuration. No action options supported
status Checks whether Code Manager and file sync are responding. You can specify a log level:
  • none
  • trace
  • info
  • warn
  • error
  • fatal
If unspecified, the default is info.

puppet-code deploy action options

You can use these action options to modify the puppet-code deploy action.

Option Description
--all or an environment name Required. You must specify either a single environment's name or use --all to deploy all environments.
--dry-run Tests the connections to each configured remote and, if successfully connected, returns a consolidated list of the environments from all remotes. The --dry-run flag implies both --all and --wait.
--format or -F Applies pretty printing to the response.
--wait or -w Refer to: Return deployment results (--wait)

puppet-code configuration settings

You can temporarily override puppet-code.conf settings on the command line.

Setting Description *nix and macOS default value Windows default value
cacert Specifies the path to the Puppet CA certificate to use when connecting to the Code Manager service over SSL. /etc/puppetlabs/puppet/ssl/certs/ca.pem C:\ProgramData\PuppetLabs\puppet\etc\ssl\certs\ca.pem
token-file Specifies the location of the file containing the authentication token for Code Manager. ~/.puppetlabs/token C:\Users\<USERNAME>\.puppetlabs\token
service-url Specifies the base URL to call the Code Manager service. https://<PRIMARY_HOSTNAME>:8170/code-manager https://<PRIMARY_HOSTNAME>:8170/code-manager