ForgeBox allows you to publish packages that only you can see and install. You'll be able to view your private package from the CLI, in the ForgeBox.io search, and in your ForgeBox.io profile, but these packages will now show up for any other users.

Publishing private packages to ForgeBox

To create a private package, set the private property to true in your box.json prior to publishing.

package init
package set private=true
package set slug=my-slug@forgeBoxUser
etc...
publish

Installing private packages from ForgeBox

Replace forgeBoxUser with your actual ForgeBox username. When you install the package, you'll need to use the full slug like so:

install my-slug@forgeBoxUser

You can install specific versions or version ranges as you would expect:

install my-slug@forgeBoxUser@1.0.0
install my-slug@forgeBoxUser@be

Private packages will be a paid feature for ForgeBox Pro subscribers, though the feature is currently available to all users for free.

There are several options you can use to control how a package is installed.

Saving dependencies

By default, any package you install will be saved as a dependency. To save it as a development dependency instead, use the --saveDev flag.

install testbox --saveDev

If you DON'T want the package you're installing to be saved as a dependency pass save=false or negate the save flag as --!save.

install cborm --!save

Production Installation

When you install a package, all dependencies will be installed. If you want to skip development dependencies, use the --production flag. This will also cause CommandBox to obey the package's ignoreList property in its box.json.

install cbvalidation --production

Verbose Installation

If you're a glutton for information, or perhaps you just want to debug what's going on, set the --verbose flag to get extra debugging information out of the install command including a list of every file that's installed.

install cbi18n --verbose

Forced Installation

If CommandBox sees the directory that it was going to install into already exists with a newer or equal version of the package inside, it will decline to install again since it would be overwriting what's already there. If you want to install anyway, use the --force flag.

install cbsoap --force

There are several factors that determine where a package gets installed to. Here are the ways CommandBox determines the install location in order of importance.

1. The value of the directory parameter passed into the install command by the user.

2. The value of the installPaths.packageName property set in the project's main box.json by the user.

3. The value of the directory property in the package's box.json by the package author. Note, this must be a path relative to the current working directory (CWD).

4. Based on the package type convention if the package is a command, coldbox module, commandbox module, plugin, or interceptor.

5. The current working directory (CWD)

Once the installation directory is determined, a folder is created that matches the package's slug which is where the package is finally copied to. If the package's createPackageDirectory property is set to false in the box.json, the package will be copied to the root of the installation directory. An example of this would be a complete application that needs to go in the web root.

CommandBox functions as a package manager which means you can use it to locate and install code packages for you. This gives you a consistent and scriptable method to install the libraries you need in a simple manner.

By default, the list of available packages is on ForgeBox, our CFML code sharing site. Additional endpoints such as Git, HTTP/HTTPS, and local file/folder are also available. When a package is installed, all of its dependencies are automatically installed for you for quick, easy experience.

You can easily create your own packages and register them on ForgeBox so the whole community can start using them.

Advanced Installation

In the CFML world, there are no global conventions for where to install things to nor where to store dependencies. Therefore, CommandBox for the most part will just stick packages in the root of your site unless you tell it otherwise. It may not be pretty, but it's as good as stock CFML apps can get. That means a lot of the cool things other package managers like NPM can do simply won't be available to you.

If you're using the ColdBox MVC Platform, congratulation! You just unlocked advanced mode! ColdBox uses conventions that tells you where to put stuff, and most importantly it has modularity as a first class citizen. Not only that, but modules can be nested infinitely to nicely encapsulate dependencies and WireBox will automatically find and register each module's models for your application to use.

Module Conventions

Modules are basically smart packages and when CommandBox installs or uninstalls modules it will behave a bit differently to take advantage of the functionality only available to the CFML world via the ColdBox Platform.

When installing a module, it will be placed in the modules/ directory. That means the cbvalidation module will install here:

The cbvalidation module has dependencies of its own but it is an island unto itself and will encapsulate these. Therefore the cbi18n module will be installed in a modules/ folder inside cbvalidation.

You'll be able to see a nice representation of this when you use the list command.

Moduleplicity

What this opens the door for is more than one module to depend on different versions of the same second module. Both can be installed and nested under the respective parent. In the near future, WireBox will be smart enough to present these nested modules only to their parents so they are fully encapsulated.

The idea is that a module can "see" and use another module installed at the same level or higher in the hierarchy, but not lower. That makes dependencies a bit of a black box to their parents. This also allows us to bypass some redundancy. For instance, when installing a module, if a satisfying version of that module already exists at a higher level, we skip the installation. Consider this example:

We know that cbvaliation requires cbi18n, but since it is already installed in the root modules folder, we won't install it again under cbvalidation.

Smart Uninstall

The last way modules are better than sliced papusas is in how they uninstall. We talked about how non-modules install-- just littered in the web root in a jumble of dependencies. When uninstalling a non-module package, CommandBox will recursively go through the dependencies and remove them as well. However, when uninstalling a module, that module's folder is simply deleted and that's it. Since all dependencies are contained in the "black box", there's no need to go hunting for them.

The install command is used to tell CommandBox what you want. Here we ask for the stable release of the ColdBox MVC Platform. "coldbox" is the name of the ForgeBox slug.

Packages should always have a box.json descriptor file inside them. This is especially true of packages installed from endpoints other than Forgebox since they don't have any other metadata available. CommandBox will install any zip file even if it doesn't have a box.json, but this isn't ideal since the name, version, and type of the package must be guessed in that instance.

If you find a package on the internet that doesn't have a box.json, please contact the maintainer and request that they add one or submit a pull request!

ForgeBox Semantic Versioning Support

ForgeBox supports semantic version ranges for installing packages. Here are some examples:

Install Process

When you install a package, here are the steps that are taken. Most all of this should be evident by the output streamed to the console during the install process. To get even more juicy details, use the --verbose flag while installing.

1. CommandBox inspects the ID passed to the install command to determine the endpoint to use.

2. The matching endpoint is asked to fetch the package represented by the ID.

3. For example, the ForgeBox endpoint checks the local artifact cache and possibly downloads the package.

4. If ForgeBox is offline, the best match package will be looked for in your artifacts.

5. The package is unzipped and its box.json is read

6. Installation directory is finalized

7. Contents of package are copied based on the ignoreList and --production flag

8. The package is saved as a dependency in the root box.json

9. The package's dependencies are installed

ForgeBox is an online registry of packages run by Ortus Solutions. The web UI for ForgeBox is located at . 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:

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

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:

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

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 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.

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:

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

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

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 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.

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

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

• File - A local file containing a package

• Folder - A local folder containing a package

• Git - Any Git repo containing a package

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

• S3 - A package zip stored in a private S3 bucket

• CFLib - UDFs posted on CFLib.org

• RIAForge - Projects posted to RIAForge.org

• Gist - A package hosted as a Gist from gist.github.com

Examples

CommandBox can be extended by modules installed from external locations. When you install a CommandBox module, it will automatically be placed in the correct modules location (inside your CommandBox installation) regardless of where you run the install command from.

Later, if you want to view, uninstall, update, or otherwise interact with these system modules, you can just use the standard package management commands, but add the --system flag to them. Any time you add that flag, the current working directory will be ignored, and you'll be interacting with the core modules installed into CommandBox.

The package commands that accept a --system flag are as follows:

• package install

• package uninstall

• package outdated

• package list

• package update

• package show

• package set

• package clear