For CommandBox to be able to install packages for you it needs to connect to package registry where packages are stored so it can download them for installation. CommandBox integrates seamlessly with ForgeBox, our community of ColdFusion (CFML) projects. CommandBox also integrates with HTTP(S), local file/folder, and Git endpoints.

Supported Endpoints

Here is a list of the package endpoints currently supported by CommandBox.

• ForgeBox - Cloud-based packages (Read more)

• HTTP(S) - Point to a hosted zip file containing a package (Read more)

• File - A local file containing a package (Read more)

• Folder - A local folder containing a package (Read more)

• Git - Any Git repo containing a package (Read more)

• Java - Install OpenJDK for your servers (Read more)

• Jar - A jar file hosted via HTTP that's not contained in a zip file (Read more)

• Lex- A Lucee Extension hosted via HTTP that's not contained in a zip file (Read more)

• S3 - A package zip stored in a private S3 bucket (Read more)

• CFLib - UDFs posted on CFLib.org (Read more)

• Gist - A package hosted as a Gist from gist.github.com (Read more)

Examples

install coldbox@3.8.1
install http://www.site.com/myPackage.zip
install /var/libs/myPackage.zip
install /var/libs/myPackage/
install git://github.com/username/repoName.git#v1.5.6

ForgeBox is an online registry of packages run by Ortus Solutions. The web UI for ForgeBox is located at http://forgebox.io. Signing up for a ForgeBox account is quick, easy, and free. You will need your own account to post packages, but anyone can browse and install packages anonymously.

Installation

Every package on ForgeBox has a unique slug. To install a package, use the slug like so:

install cborm

You can also specify the version of a package you want to install from Forgebox.

install coldbox@3.8.1

Given the install command above, if the file ~/.CommandBox/artifacts/coldbox/3.8.1/coldbox.zip exists on your hard drive, the installation will not connect to Forgebox at all. It will be a completely offline installation. This only works when you type an exact version that includes a major, minor, and patch number.

In box.json

You can specify packages from ForgeBox as dependencies in your box.json in this format:

{
    "dependencies" : {
        "coldbox" : "^4.1.0"
    }
}

info The caret ^ means that the update command will update minor releases but not major releases.

Installing Lucee Extensions

If the package being installed from ForgeBox is of type lucee-extensions and if the current working directory is found to have a Lucee server in it, the lex file will instead be installed to the server context's deploy folder. Note the Lucee server will need to have been started at least once so CommandBox "knows" about it, but it need not be running at the time.

install 5C558CC6-1E67-4776-96A60F9726D580F1

ForgeBox Pro

For companies who want to host internal code endpoints for private packages, we will soon support an Enterprise version of ForgeBox that can be installed behind your company's firewall. Please contact us if this feature interests you.

ForgeBox namespace

Inside CommandBox, use the forgebox namespace to search for packages or show packages of your choosing.

forgebox search

The first command to try out is "forgebox search". It takes a single parameter which is a string to perform a case-insensitive search for. Any entry whose title, summary or author name contains that text will be displayed:

forgebox search awesome

forgebox show

The "forgebox show" command takes several parameters and is pretty flexible. The first way to use it is to just view the details of a single entry using the slug.

forgebox show coldbox

You can get lists of items filtered by package type (modules, interceptors, caching, etc) and ordered by popular, new, or recent. Here's some examples:

forgebox show plugins
forgebox show new modules
forgebox show recent commandbox-commands

Too many results on one page? Use the built-in pagination options:

forgebox show orderby=new maxRows=10 startRow=11

Or just pipe the output into the built-in "more" or "grep" command.

forgebox show new | more
forgebox show modules | grep brad

forgebox show help

If you have troubles remembering the valid types or order by's, remember you can always hit "tab" for autocomplete within the interactive shell. Adding "help" to the end of any command will also show you the specific help for that command.

forgebox help
forgebox search help
forgebox show help

forgebox types

The list of types in ForgeBox is dynamic so we don't list them out in the help. Instead, we made a handy "forgebox types" command to pull the latest list of types for you.

forgebox types

Packages that are either stored locally on your machine or are accessible via a network drive as a zip file can be installed by using their file system path. The path can be absolute or relative.

Make sure your package zip file has a box.json inside of it so CommandBox can tell the version and name of the package. If there is no box.json, the name of the file without the extension will be used as the package name.

Installation

To install a package from a local file, use the path like so:

install /var/libs/myPackage.zip

Note if using Windows, you need to escape backslashes in the command parameter.

install C:\\websites\libs\\myPackage.zip

Relative paths will start in the directory where the command is being run from.

install libs/myPackage.zip
install ../../libs/myPackage2.zip

In box.json

You can specify packages from file endpoints as dependencies in your box.json in this format. Remember, JSON requires that backslashes be escaped.

{
    "dependencies" : {
        "myPackage" : "/var/libs/myPackage.zip"
        "myPackage2" : "C:\\websites\libs\\myPackage2.zip"
    }
}

Packages that are either stored locally on your machine or are accessible via a network drive in an unzipped folder can be installed by using their file system path. The path can be absolute or relative.

Make sure your package folder has a box.json inside of it so CommandBox can tell the version and name of the package. If there is no box.json, the name of the last folder in the path will be used as the package name.

Installation

To install a package from a local folder, use the path like so:

Note if using Windows, you need to escape backslashes in the command parameter.

Relative paths will start in the directory where the command is being run from.

In box.json

You can specify packages from folder endpoints as dependencies in your box.json in this format. Remember, JSON requires that backslashes be escaped.

Packages hosted on a website as a zip file can be installed by using the direct URL to the package. Both HTTP and HTTPS URLs are supported. If the URL returns a 301 or 302 redirect, it will be followed until the package is reached.

Make sure your package zip file has a box.json inside of it so CommandBox can tell the version and name of the package. If there is no box.json, the following rules will be decided to determine the name of the package:

1. If the URL has the zip file name in it, the name without ".zip" is used.

2. If the URL contains github.com, the repo name will be used.

3. Otherwise, the entire URL will have non alpha-numeric characters removed and used.

Installation

To install a package from a website, use the full URL like so:

In box.json

You can specify packages from HTTP(S) endpoints as dependencies in your box.json in this format:

Cached URLs

If you know a given URL will always return the exact same package, then you can request CommandBox to cache the download in local artifacts to speed up builds. To do so, use an endpoint name of https+cached or http+cached in your install ID.

Or

Cached artifacts will be stored under the slug HTTP_Cached and can be viewed like so:

If you have external Lucee Extensions that need downloaded into your Lucee Server, you can use the lex: endpoint to download them. The lex endpoint does not expect the download to be contained in a zip file or to have a box.json. As such, there is no real package slug or name, so CommandBox will "guess" the name based on the name of the lex based on the URL.

install lex:https://server.com/path/to/ortus-redis-cache-1.4.0.lex

The Lex endpoint can also be used to install local lex files.

install lex:C:\path\to\my.lex
install lex:/path/to/my.lex
# Windows UNC path
install lex:\\\\serverName\sharename\my.lex

Please note that if a Lucee extension is already hosted on ForgeBox, you do not need the Lex extension, as you can simply use the ForgeBox slug just like you would any other page and get the same result but with the addition of semantic versioning.

install 5C558CC6-1E67-4776-96A60F9726D580F1

Installation Path

Files from the lex: endpoint will be placed in a folder named the same as the package by default unless you provide another folder for installation. If the current working directory is found to have a Lucee server in it, the lex file will instead be installed to the server context's deploy folder. Note the Lucee server will need to have been started at least once so CommandBox "knows" about it, but it need not be running at the time.

In box.json

You can specify a lex as dependencies in your box.json in this format.

{
    "dependencies":{
        "ortus-redis-cache-1.4.0":"lex:https://server.com/path/to/ortus-redis-cache-1.4.0.lex"
    }
}

This means you can run a box install on a fresh project to pull down extensions needed for your app to run.

CommandBox can install UDFs from the popular site CFLib.org. Each project on CFLib is a single CFML function. You can find UDFs via the web site and copy the URL slug for a given UDF to use in your installation.

For example, if the URL to a given UDF is http://www.cflib.org/udf/CalculateWindChill, the slug you'll want to use would be CalculateWindChill.

Standard Installation

To install a package from CFLib, use the slug from the website's URL like so:

install cflib:AreaParallelogram

This will create a folder in your installation directory named after the UDF containing a .cfm file of the same name. The above command would create the following folder:

AreaParallelogram/AreaParallelogram.cfm

That file contains a single function that you can call. It is up to you to include that file where ever you want to use the UDF.

include '/AreaParallelogram/AreaParallelogram.cfm';
var area = AreaParallelogram( base, height );

ColdBox Installation

If you're using ColBox, you can use a slightly different version of the CFLib endpoint called CFLib-ColdBox which will wrap up the UDF inside a CFC and place it in an ad-hoc module which automatically registers the model with WireBox.

install cflib-coldbox:AreaParallelogram

This frees you up from needing to manually include the file. Once you install the module, you can immediately ask WireBox for the UDF using the convention UDFName@cflib. WireBox will register this mapping by convention so there is no additional setup required to use the UDF.

var area = getInstance( `AreaParallelogram@cflib` ).AreaParallelogram( base, height );

Or inject the wrapped UDF to use in your handlers or models.

component {
    // Inject the UDF wrapped in a CFC
    property name='areaHelper' inject='AreaParallelogram@cflib';

    function onDIComplete() {
        var area = areaHelper.AreaParallelogram( base, height );
    }
}

Package Metadata

Packages installed from the CFLib endpoint don't have any way to get new version information. They will always show as outdated using the outdated or update commands and their downloads will not get stored in the artifact cache.

In box.json

You can specify packages from the CFLib endpoint as dependencies in your box.json in this format.

{
    "dependencies" : {
        "AreaParallelogram" : "cflib:AreaParallelogram"
        "FahrenheitToCelsius" : "cflib-coldbox:FahrenheitToCelsius"
    }
}

Packages hosted in private S3 buckets can be installed directly from S3 URLs.

Installation

To install a package from a S3 bucket, use a URL like so:

install s3://my-private-bucket/myPackage.zip

The S3 endpoint will automatically determine which region your bucket is in order to download your package. You can, however, bypass this automatic bucket region resolution by encoding the region of your bucket into the S3 path by using a : after the bucket name:

install s3://my-private-bucket:eu-west-2/myPackage.zip

Info If your S3 path does not end in .zip the S3 endpoint will make a HEAD request to S3 for the package path to determine if your package exists at that location. If it does not, then .zip will be appended to your S3 path and that new path will be used as the location of your package. This means it is possible for you to specify a package without adding the .zip extension: s3://my-private-bucket/myPackage.

In box.json

You can specify packages from S3 endpoints as dependencies in your box.json in this format:

{
    "dependencies" : {
        "myPackage" : "s3://my-private-bucket/myPackage.zip"
    }
}

Authentication

In order for S3 endpoints to be resolved, CommandBox needs an AWS access key and AWS secret key belonging to an AWS IAM user or role that has permission to get objects from the S3 bucket where the package is stored. The access and secret keys can be set in CommandBox settings either globally:

config set endpoint.s3.aws_access_key_id=XXXXXXXXXX
config set endpoint.s3.aws_secret_access_key=XXXXXXXXXX

or on a per bucket basis:

config set endpoint.s3.my-private-bucket.aws_access_key_id=XXXXXXXXXX
config set endpoint.s3.my-private-bucket.aws_secret_access_key=XXXXXXXXXX

If aws_access_key_id and aws_secret_access_key are not set in your CommandBox settings, the S3 endpoint checks for credentials in the same places and order as the AWS CLI and SDKs:

It checks for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables containing the credentials.

It checks for an AWS credentials ini file. (If you use the AWS CLI, this file is created by the CLI when you enter your credentials during setup. The default location for this file is at~/.aws/credentials.)

Info The location of the credentials ini file can be overwritten by setting anAWS_SHARED_CREDENTIALS_FILE environment variable to an alternate file path (this can also be set in your CommandBox settings:endpoint.s3.aws_shared_credentials_file). Further, the AWS credentials file has the concept of "profiles", where the default profile is named "default". The profile to use can be changed from "default" by setting an alternate profile name in anAWS_PROFILE environment variable or CommandBox endpoint setting (endpoint.s3.aws_profile).

Finally the S3 endpoint will check for the presence of an IAM role from which credentials can be obtained. This credential location is only valid on AWS EC2 instances.

The full list of possible credential locations and the order in which they are checked is as follows:

• Per bucket credentials in your CommandBox endpoint settings

• Global credentials in your CommandBox endpoint settings

• Environment variables

• AWS credentials file

• IAM role

The Java endpoint is capable of downloading and installing any version of Java in the AdoptOpenJDK API. Use the java search command to search the API to find what Java versions are available. The endpoint will use the local artifacts cache.

java search version=openjdk8 release=

NOTE: If you simply want to start a server with a given version of OpenJDK, you don't need to use this endpoint directly, You can ask CommandBox to use a specific java version and it will handle the installation for you as well as re-using identical Java installs across servers. For example:

java install OpenJDK8_jdk8u181b13

Installation ID

The installation ID consists of a series of identifiers separated by underscores that describe the Java version, type, JVM, etc that you want installed.

install java:<version>_<type>_<arch>_<os>_<jvm-implementation>_<release>

An example utilizing every option would be

install java:OpenJDK8_jre_x64_windows_hotspot_jdk8u181b13

However, everything is optional except the major version. These are also valid installation IDs

install java:openjdk8
install java:openjdk8_jre
install java:OpenJDK8_jdk8u181b13
install java:OpenJDK8_jdk_jdk8u181b13

ID Definitions

Here are the possible options for each section of the ID.

• version - openjdk8, openjdk9, openjdk10, etc...

• type - jdk, jre

• arch - x64, x32, ppc64, s390x, ppc64le, aarch64, arm etc...

• os - windows, linux, mac, solaris, alpine_linux (openjdk11+ only)

• jvm-implementation - hotspot

• release - latest, jdk8u172, jdk8u172-b00, etc...

Defaults

For items not specified in the endpoint ID, the endpoint will default as follows:

• type - jre

• arch - Whatever the current OS arch is

• os - Whatever the current OS is

• JVM-implementation - hotspot

• release - latest

Installation Folder

When java is installed as a package endpoint, the name of the folder that it is installed into will mirror the ID you use. This means two different installation IDs that resolve to the exact same Java version may end up in different folders. We do this for a couple reasons. One of which is simplicity, the other is that if you have configuration expecting a specific folder name, Mac users and Windows users may get a different download, but if the id is simple java:openjdk8_jdk, they would both install into a folder called openjdk8_jdk.

This endpoint will NOT edit your registry, create any symlinks, or add environment variables. It will simply drop the Java installation into a folder so you can point servers at it. You are free to use one of these Java installations in such a manner, but we don't do this by default so you can install as many java versions as you like and they don't fight with each other.

CommandBox can install a Github Gist from gist.github.com as a package.

Make sure the root of your Git repo has a box.json inside of it so CommandBox can tell the version and name of the package. If there is no box.json, the name of the Gist ID will be used as the package name.

Installation

To install a package from a Github Gist, you must pass the Gist ID from gist.github.com:

install gist:<gistID>
install gist:b6cfe92a08c742bab78dd15fc2c1b2bb

The Github username is optional.

install gist:<username>/<gistID>

You can target a specific commit by adding a "commit-ish" after the Gist ID.

install gist:b6cfe92a08c742bab78dd15fc2c1b2bb#37348a126f1f410120785be0d84ad7a2148c3e9f

In box.json

You can specify packages from folder endpoints as dependencies in your box.json in this format. Remember, JSON requires that backslashes be escaped.

{
    "dependencies" : {
        "myPackage" : "gist:gistID"
    }
}

If you have external jars that need downloaded into your project, you can use the jar: endpoint to download them. The jar endpoint does not expect the jars to be contained in a zip file or to have a box.json. As such, there is no real package slug or name, so CommandBox will "guess" the name based on the name of the jar (if a jar name appears in the path or query string).

Installation path

Files from the jar: endpoint will be placed in a lib/ folder by default unless you provide another folder for installation.

In box.json

You can specify jars as dependencies in your box.json in this format.

Note this installation method does not include any dependencies of the jar like a Maven installation would. That will be a future endpoint.

Semantic Versioning

The jar endpoint will make the following assumptions about what version of a jar a particular URL may point to:

• It tries and parse a semantic version from the URL's path

• It will store that version in the package's box.json (0.0.0 if not found)

• It will use that version when checking for updates to the jar

This will be reflected in what you see in the package list and outdated commands.

So for example, if you install a jar dependency like so:

CommandBox will parse out the 1.24.0 from the path of the URL and will assume that as the version of the package. When checking for outdated dependencies, that version will be used to compare to the current URL in your box.json which means an unchanged URL will know it is not out of date.

Entire Git repos that represent a package can be installed via the Git endpoint. This can be a public Git server like GitHub or Bitbucket, or a private Git repo behind your firewall.

Make sure the root of your Git repo has a box.json inside of it so CommandBox can tell the version and name of the package. If there is no box.json, the name of the repo will be used as the package name.

Installation

To install a package from a Git repo, use the URL like so:

You can target a specific branch, tag, or commit by adding a "commit-ish" to the end of the URL.

If you don't specify a commit-ish, the Girt endpoint will assume you want the master branch. If there is no master branch, we will attempt to checkout the main branch.

GitHub shortcut

If the repo you wish to install is located on Github.com, you can use this shortcut to specifying the package.

In box.json

You can specify packages from folder endpoints as dependencies in your box.json in this format. Remember, JSON requires that backslashes be escaped.

Authentication

Git repos that allow anonymous pulls do not require any additional configuration for authentication. CommandBox's Git endpoint supports SSH authentication via public/private keys by using the git+ssh:// protocol.

Some Git endpoints (like private Github repos) need a user before the site name in the url string like below:

Info Note the git+ssh URL is a little different than a HTTP(S) URL. There is a colon (:) after the host instead of a forward slash (/).

The git+ssh endpoint will look for a private SSH key in your ~/.ssh directory named id_rsa, id_dsa, or identity. If you are using a multi-key setup with a ~/.ssh/config file, it will be read, and the appropriate key will be used for the host. The matching public key needs to be registered in the Git server.

Info If you are deploying to a server and you have not previously logged into the Git server from the new machine you will need to make sure the Git server is added to your known_hosts file. The quickest way to do this is to use git clone git@github.com/user/repo.git from the terminal OR add the line from your local machine to the server.

Note:

If you receive an invalid private key exception (Error cloning git+ssh repository and com.jcraft.jsch.JSchException: Auth fail), check your version of SSH. OpenSSH (7.8 and newer) generates keys in the new OpenSSH format, which starts with -----BEGIN OPENSSH PRIVATE KEY-----. JGit does not support this key format. Generate your key in the classic format using the following:

Password authentication

You can authenticate to a Git repo over HTTP using a username/password combination or a personal access token. The format looks like this:

Github

Github personal access tokens can be specified as either

or just the personal access token like

and they both appear to work the same. It appears that a private Github repo requires the “repo” scope selected for the personal access token.

GitLab

GitLab seems to want a username, but it doesn’t seem to matter what the username is.

Env Vars

You can use environment variables from the CLI or in your box.json to protect sensitive information like passwords and keys.

NetRC

We also support the NetRC file format. Just create a files in your user's home directory called ~/.netrc or ~/_netrc with the following format:

CommandBox will find this file, match the hostname to the Git repo being cloned, and use the username and password as specified.

Note:

We do not support any of these username/password options over HTTP as it just seems unwise. Please use HTTPS.

Known Behaviors

Some users of Circle-CI have reported the following error when trying to clone a Git repo over HTTPS.

It is changing the https github url to ssh in the call. You can remove the config setting like so: