Skip to main content

Command Line (CLI)

A set of command line tools are available using the tool certify.exe which is found in the installation directory. The commands must be performed using an elevated administrators account.

tip

Most users do not need to use the command line options at all. By default all certificate renewals are taken care of automatically by the Certify background service.

This page covers the certify command line for Certify Certificate Manager. Certify Management Hub has its own command line tool, see Hub CLI.

Usage: certify <command>

Run certify with no arguments to list the available commands.

Connecting over a named pipe​

The command line tool talks to the local Certify background service. If the service has been switched to the named pipe transport, add --pipe anywhere in the command to connect over the named pipe instead of http, e.g. certify list --pipe. You can also set the environment variable CERTIFY_CLIENT_MODE=namedpipe to do the same for every command.

The named pipe can only be opened from an elevated command prompt.

Manage ACME Accounts​

  • certify acmeaccount list: list registered acme account details (JSON output)

  • certify acmeaccount add <ACME CA ID> <your contact email> <optional EAB key id> <optional EAB Key>: add a new ACME account, use --staging to add it as a staging (test) account

You can use the acmeaccount add command to add/create a new ACME account registration. Using this command implies your agreement with the chosen ACME CAs current terms and conditions :

Example - Create Let's Encrypt Account:​

certify acmeaccount add letsencrypt.org hosting@example.com

Example - Add Zero SSL Account with your EAB key id and key:​

certify acmeaccount add zerossl.com hosting@example.com "abcdkeyid" "_Example_Key_Value_"

Example - Create Let's Encrypt Staging Account:​

certify acmeaccount add letsencrypt.org hosting@example.com --staging

Certificate Authorities​

  • certify ca list : list the available certificate authorities and their details (JSON output). The Id of each item is the CA ID used by other commands.

  • certify ca setpreferred <CA ID> : set the preferred certificate authority for this instance, e.g. certify ca setpreferred letsencrypt.org. Use certify ca setpreferred any to clear the preference.

Instance Settings​

  • certify settings : show the current instance settings (JSON output).

Listing Managed Certificates​

  • certify list : list managed certificates and current running/not running status in IIS

  • certify list --json <path-to-output-json> : output list of managed certificates as JSON to a given file path.

Performing Renewals and Deployment Tasks​

  • certify renew : renew certificates for all auto renewed managed certificates, if they are due or have not yet been requested.

  • certify renew id=<first item id>,<next item id> : target the specific comma separated list of IDs (no spaces), optionally with other renewal flags.

    • A targeted item whose certificate was obtained but not fully deployed (the certificate store or binding deployment failed, or an automated deployment task did) has that certificate deployed again rather than a new one requested. Add --force-renew-all to request a new certificate regardless.

  • certify renew --renew-all-due : renew all certificates which are due or have not yet been requested even if auto-renew is not enabled.

  • certify renew --force-renew-all : renewal for all auto renewed certificates even if they are not yet due.

  • certify renew --renew-witherrors : attempt renewal for all certificates which have most recently failed to renew.

  • certify deploy "<managed cert id>" "<task id>" : perform a specific deployment task for the given managed certificate. See the Manual trigger mode for deployment tasks.

Adding or Removing Managed Certificates​

  • certify importcsv : import managed certificates from a CSV file. See CSV Import for more details

The certify add and certify remove commands can be used to add or remove domains from an existing managed certificate or create a new managed certificate. You can find the correct managed certificate ID in the app under Certificate > Advanced > Actions > Managed Certificate Reference Id (e.g. a02e3afe-49ba-470a-83e5-2e397aa946eb:1). The remove command accepts any as the managed cert id to remove the matching domains from any managed certificates.

These will not request/renew the actual certificate unless you append --perform-request to the end of the command. These commands assume the same domain validation settings are being used for all domains on the same managed certificate:

  • certify remove <managed cert id, or any> domain1.test.com;domain2.test.com : remove one or more certificates from the configuration of a managed certificate. If removing a domain will mean there are zero domains remaining on the certificate then the managed certificate will be removed completely.

  • certify add <managed cert id, or new> domain1.test.com;domain2.test.com : add one or more additional domains to the configuration of a managed certificate. e.g. certify add new example.com

  • certify add new domain1.test.com;domain2.test.com --template C:\Temp\managedcert-template.json : add new managed cert with given domain, using a template (json exported from an existing managed cert).

using templates

Templates are an advanced feature intended only for users who require managed certificate automation with non-default challenge configuration (e.g. DNS validation).

To generate a template:

  • Use certify list --json output.json to export your managed certificates as JSON
  • Edit the JSON file down to a single item, removing the array [ ... ]
  • Save the file as your new template. Domains etc will be discarded from the template and you still need to provide these arguments

Templates are not guaranteed to stay compatible between major version updates so you should test integrations which use them with each new release.

Stored Credentials​

For advanced automation scenarios you can add/update stored credentials or list your existing items:

  • certify credential store <unique storage key GUID> "<title>" "<type id>" "<secret values as JSON>" : for advanced automation use. Stores or updates a stored credential.

  • certify credential list : list current stored credential summary information. This does not show secret values.

Note that when storing credentials information such as the Type ID and JSON format for the secrets will vary by credential type and are not arbitrary. See an export of the current list on github or contact support to discuss your requirements.

Below is an example command adding a stored credential for the Cloudflare DNS API. The GUID ID is generated by you and just needs to be unique where you are using it:

./certify credential store "00213bb0-ec38-49db-bbec-f38f40e91809" "A test credential" DNS01.API.Cloudflare "{'apitoken':'anexampletokenvalue'}"

Joining a Management Hub​

  • certify hub join <url of mgmt hub API> <client id> <client secret> : join this instance to a Certify Management Hub so it can be administered centrally. Prints Joined Hub OK on success, otherwise the reason the join failed.

The Client ID and Client Secret come from a joining API key in the Hub, under Settings > Security > API Access (one is created automatically when the Hub is installed). This is useful for joining instances as part of an automated deployment. See joining CCM to the Hub for the full joining process and security considerations.

warning

The Hub has full control over the instance settings, including deployment tasks that may run local code. Do not join a Hub you don't control or trust.

Diagnostics​

  • certify diag : check existing ssl bindings and managed certificate integrity

  • certify httpchallenge keys=stop,configcheck : run the temporary http challenge server on port 80 to test firewall and routing configuration. This uses http.sys to register a listener for ACME http challenges as http:/*/.well-known/acme-challenge/ and will not conflict with IIS. The server will run for 60 seconds after the last matching request is received or until stopped by calling the control key.

With the example control key stop and config check key configcheck you can:

  • test your servers response using http://<your domain or server ip>/.well-known/acme-challenge/configcheck e.g. http://127.0.0.1/.well-known/acme-challenge/configcheck
  • stop the service using http://<your domain or server ip>/.well-known/acme-challenge/stop.

The user agent returned should be Certify/HttpChallengeServer

Backup and Restore​

Backups use the same file format as Settings > Import & Export in the app, see Import & Export for migration guidance.

  • certify backup export <directory or full filename> <encryption secret> : export the instance configuration, including managed certificates, stored credentials and certificate files, to a backup file encrypted using the given secret. If a directory is given the file is named certifytheweb_export_<yyyyMMdd>.json.

  • certify backup import <full filename> <encryption secret> : import a backup file, using the same secret it was exported with.

  • certify backup import preview <full filename> <encryption secret> : test a backup file and show what would be imported, without importing anything.

Keep backup files and their secrets safe, as together they give access to your stored credentials and certificates.

Managing license activation​

  • certify license activate <email> <key> : activate the license for this instance of Certify Certificate Manager. Useful for larger scale automated deployments.

  • certify license deactivate <email> : deactivates the license for this instance of Certify Certificate Manager.

  • certify license check : check the license status of this instance (JSON output). The Status is licensed, unlicensed or invalid (applied but expired or otherwise invalid). The command exits with code 0 if the instance has a valid license and -1 otherwise, so it can be used in scripts.

The older forms certify activate <email> <key> and certify deactivate <email> still work.