CommandBox : CLI, Package Manager, REPL & More
5.1.0
5.1.0
  • Introduction
  • About This Book
  • Authors
  • Overview
  • Getting Started Guide
  • Setup
    • Requirements
    • Download
    • Installation
    • Light and Thin Binaries
    • Non-Oracle JREs
    • Upgrading
    • Common Errors
  • Usage
    • Execution
      • Recipes
      • CFML Files
        • Using a DB in CFML scripts
      • OS Binaries
      • CFML Functions
      • Exit Codes
    • Commands
    • Parameters
      • Escaping Special Characters
      • File Paths
      • Globbing Patterns
      • Piping into Commands
      • Expressions
    • Command Help
    • Environment Variables
    • System Settings
    • Ad-hoc Command Aliases
    • Default Command Parameters
    • REPL
    • Tab Completion
    • Interactive Shell Features
    • forEach Command
    • Auto Update Checks
    • Bullet Train Prompt
    • 256 Color Support
    • A Little Fun
  • IDE Integrations
    • Sublime Text
    • Visual Studio Code
  • Config Settings
    • Module Settings
    • Proxy Settings
    • Endpoint Settings
    • Server Settings
    • Misc Settings
  • Embedded Server
    • Multi-Engine Support
    • Start HTML Server
    • Offline Server Starts
    • Debugging Server Starts
    • Server Processes
    • Manage Servers
    • FusionReactor
    • Server Logs
    • Configuring Your Server
      • JVM Args
      • Server Port and Host
      • URL Rewrites
      • Aliases
      • Custom Error Pages
      • Welcome Files
      • Basic Authentication
      • Custom Java Version
      • Adding Custom Libs
      • GZip Compression
      • REST Servlet
      • Performance Tuning
      • Undertow Options
      • Custom Tray Menus
    • External Web Server
    • Starting as a Service
    • Server.json
      • Working with server.json
      • Packaging Your Server
      • Using Multiple server.json Files
  • Package Management
    • Installing Packages
      • Installation Path
      • Installation Options
      • Advanced Installation
    • Private Packages
    • System Modules
    • Code Endpoints
      • ForgeBox
      • HTTP(S)
      • File
      • Folder
      • Git
      • Java
      • S3
      • CFLib
      • Jar (via HTTP)
      • Lex (via HTTP)
      • Gist
    • Package Scripts
    • Dependencies
    • Semantic Versioning
    • Updating Packages
    • Creating Packages
      • Editing Package Properties
      • Publishing Lucee Extensions to ForgeBox
    • Artifacts
    • Box.json
      • Basic Package Data
      • Extended Package Data
      • Package URLs
      • Installation
      • Embedded Server
      • Dependencies
      • TestBox
    • Managing Version
  • Task Runners
    • Task Anatomy
    • Task Target Dependencies
    • Passing Parameters
    • Using Parameters
    • Task Output
    • Task Interactivity
    • Shell Integration
    • Downloading Files
    • Running Other Commands
    • Error Handling
    • Hitting Your Database
    • Interactive Jobs
    • Watchers
    • Property Files
    • Running other Tasks
    • Loading Ad hoc Jars
    • Loading Ad-hoc Modules
    • Cancel Long Tasks
    • Progress Bar
  • Helpful Commands
    • Token Replacements
    • Checksums
    • Code Quality Tools
  • Deploying CommandBox
    • Docker
    • Heroku
    • Amazon Lightsail
  • TestBox Integration
    • Test Runner
    • Test Watcher
  • Developing For CommandBox
    • Modules
      • Installation and Locations
      • Configuration
        • Public Properties
        • Configure() Method
        • Lifecycle Methods
      • Conventions
      • User Settings
      • Linking Modules
    • Commands
      • Aliases
      • Using Parameters
        • Using File Globs
        • Dynamic Parameters
      • Command Output
      • Tab Completion & Help
      • Interactivity
      • Watchers
      • Shell integration
      • Running Other Commands
      • Error handling
      • Watchers
      • Loading Ad hoc Jars
    • Interceptors
      • Core Interception Points
        • CLI Lifecycle
        • Command Execution Lifecycle
        • Module Lifecycle
        • Server Lifecycle
        • Error Handling
        • Package Lifecycle
      • Custom Interception Points
    • Injection DSL
    • Example Project
    • FusionReactor for the CLI
  • ForgeBox Enterprise
    • Introduction
    • Storage
    • Commands
      • List
      • Register
      • Login
      • Set Default
      • Remove
    • Usage
Powered by GitBook
On this page
  • Ad-hoc package scripts
  • pre/post package scripts
  • Access Intercept Data

Was this helpful?

Edit on Git
Export as PDF
  1. Package Management

Package Scripts

You can define a struct in your box.json called scripts that correspond to the interception points in CommandBox. Any script defined there will be ran on during that interception point. This allows you to prescribe arbitrary commands on a package-by-package basis. You may wish to set your package location any time you bump a package version or perform a !git push on publish. Below is an example of some scripts in a box.json.

{
  "name" : "My Package",
  "slug" : "my-package",
  "version" : "1.0.0",
  "scripts" : {
   "postVersion" : "package set location='gitUser/gitRepo#v`package version`'",
   "postPublish" : "!git push --follow-tags"
  }
}

Package scripts can be named after any valid interception point and can contain any valid command that you can run from the interactive shell.

Ad-hoc package scripts

You can also create ad-hoc scripts with arbitrary names that contain a collection of often-run commands.

{
  "name" : "My Package",
  "slug" : "my-package",
  "version" : "1.0.0",
  "scripts" : {
   "build" : "!grunt build && testbox run && run-script generateAPIDocs && bump --patch && publish",
   "generateAPIDocs" : "docbox generate"
  }
}

Call these scripts at any time with the run-script command

run-script generateAPIDocs
run-script build

pre/post package scripts

Before any package script is run, CommandBox will look for another package script with the same name, but prefixed with pre. After any package script is run, CommandBox will look for another package script with the same name, but prefixed with Post. So if you have a package that contains 3 package scripts: foo, preFoo, and postFoo, they will run in this order.

  1. preFoo

  2. foo

  3. postFoo

This works for built-in package script names as well as as doc package scripts. It also works on any level. In the example above, if you created a 4th package script called prePreFoo, it would run prior to preFoo.

Access Intercept Data

Any package script fired by an internal interception announcement in CommandBox will have access to any intercept data via environment variables in the shell. All intercept data will be prefixed with interceptData. and will use "dot notation" for nested structs. You can see if the docs on what intercept data is available to each interception point.

For example, a preCommand interception announcement receives a struct called commandInfo with a key called commandString which means your package script can access that via the following environment variable:

${interceptData.commandinfo.commandString}

You can see this in action with this simple package script:

package set scripts.preCommand="echo 'You are running [\${interceptData.commandinfo.commandString}]'"

Or if you wanted to simply debug what is available to you, use the env show command in your package script to dump out all environment variables to the console.

Here's another example that writes a file to the server home directory when a server starts, using an environment variable to dynamically obtain the proper path.

package set scripts.onServerStart="touch \${interceptData.serverInfo.serverHomeDirectory}/hi.txt"

PreviousGistNextDependencies

Last updated 5 years ago

Was this helpful?