├── .gitbook └── assets │ ├── CommandBoxLogo.png │ ├── FR CLI detail.png │ ├── FR CLI history.png │ ├── box_icon (2) (2) (2) (2) (2) (2) (2) (1).png │ ├── box_icon (2) (2) (2) (2) (2) (2) (2).png │ ├── box_icon.png │ ├── command_help.png │ ├── docker.png │ ├── embedded_server.png │ ├── extensbility (1) (1).png │ ├── extensbility (1).png │ ├── first_run.png │ ├── forgebox-endpoint-default-list (1) (1).gif │ ├── forgebox-endpoint-default-list (1).gif │ ├── forgebox-endpoint-login.gif │ ├── forgebox-endpoint-register (1).gif │ ├── forgebox-endpoint-register.gif │ ├── forgebox-endpoint-remove.gif │ ├── forgebox-endpoint-set-default.gif │ ├── global_help.png │ ├── heroku.png │ ├── image (1).png │ ├── image (10).png │ ├── image (11).png │ ├── image (12).png │ ├── image (13).png │ ├── image (14) (1) (1).png │ ├── image (14) (1).png │ ├── image (14).png │ ├── image (15) (1).png │ ├── image (15).png │ ├── image (16).png │ ├── image (17).png │ ├── image (18).png │ ├── image (19).png │ ├── image (2) (2) (2) (2) (2) (2) (2) (2) (1).png │ ├── image (2) (2) (2) (2) (2) (2) (2) (2).png │ ├── image (2) (2).png │ ├── image (2).png │ ├── image (20).png │ ├── image (21).png │ ├── image (22).png │ ├── image (23).png │ ├── image (24).png │ ├── image (3).png │ ├── image (4).png │ ├── image (5).png │ ├── image (6).png │ ├── image (7).png │ ├── image (8) (1) (1) (1) (1) (1).png │ ├── image (8) (1) (1) (1) (1).png │ ├── image (8) (1) (1) (2) (2) (2) (2) (2) (1).png │ ├── image (8) (1) (1) (2) (2) (2) (2) (2) (2).png │ ├── image (8) (1) (1) (2) (2) (2) (2) (2).png │ ├── image (8).png │ ├── image (9) (1).png │ ├── image (9).png │ ├── image.png │ ├── in_the_package.png │ ├── namespace_help.png │ ├── open_package (2) (2) (2) (2) (2) (2) (2) (1).png │ ├── open_package (2) (2) (2) (2) (2) (2) (2).png │ ├── open_package.png │ ├── ortussolutions_button (1).png │ ├── ortussolutions_button.png │ ├── package_manager.png │ ├── run (1) (1) (1) (1) (2) (2) (2) (2) (2) (2) (1).png │ ├── run (1) (1) (1) (1) (2) (2) (2) (2) (2) (2).png │ ├── run.png │ ├── shalom (2) (2) (2) (2) (2) (2) (2) (1).jpg │ ├── shalom (2) (2) (2) (2) (2) (2) (2).jpg │ ├── shalom.jpg │ ├── system_tray_server_icons.png │ ├── terminal.png │ ├── the_package.png │ ├── versions.png │ ├── welcome (1).png │ └── welcome.png ├── README.md ├── SUMMARY.md ├── about-this-book.md ├── authors.md ├── config-settings ├── README.md ├── endpoint-settings.md ├── env-var-overrides.md ├── json-settings.md ├── misc-settings.md ├── module-settings.md ├── proxy-settings.md ├── server-settings.md ├── setting-sync.md └── task-runner-settings.md ├── deploying-commandbox ├── README.md ├── amazon-lightsail.md ├── docker.md ├── github-actions.md └── heroku.md ├── developing-for-commandbox ├── README.md ├── commands │ ├── README.md │ ├── aliases.md │ ├── command-output.md │ ├── error-handling.md │ ├── interactivity.md │ ├── loading-ad-hoc-jars.md │ ├── running-other-commands.md │ ├── shell-integration.md │ ├── tab-completion-and-help.md │ ├── using-parameters │ │ ├── README.md │ │ ├── dynamic-parameters.md │ │ └── using-file-globs.md │ ├── watchers-1.md │ └── watchers.md ├── example-project.md ├── fusionreactor-for-the-cli.md ├── injection-dsl.md ├── interceptors │ ├── README.md │ ├── core-interception-points │ │ ├── README.md │ │ ├── cli-lifecycle.md │ │ ├── command-execution-lifecycle.md │ │ ├── error-handling.md │ │ ├── module-lifecycle.md │ │ ├── package-lifecycle.md │ │ └── server-lifecycle.md │ └── custom-interception-points.md └── modules │ ├── README.md │ ├── configuration │ ├── README.md │ ├── configure-method.md │ ├── lifecycle-methods.md │ └── public-properties.md │ ├── conventions.md │ ├── installation-and-locations.md │ ├── linking-modules.md │ └── user-settings.md ├── embedded-server ├── README.md ├── configuring-your-server │ ├── README.md │ ├── ad-hoc-env-vars.md │ ├── ad-hoc-java-system-properties.md │ ├── adding-custom-libs.md │ ├── adobe-cfpm.md │ ├── aliases.md │ ├── bindings │ │ ├── README.md │ │ ├── open-browser-url.md │ │ ├── server-port-and-host.md │ │ ├── ssl-certs.md │ │ └── ssl-client-certs.md │ ├── case-sensitivity-of-web-server.md │ ├── console-log-layout.md │ ├── custom-error-pages.md │ ├── custom-java-version.md │ ├── custom-tray-menus.md │ ├── custom-welcome-files.md │ ├── env-var-overrides.md │ ├── experimental-features.md │ ├── gzip-compression.md │ ├── https-redirect-hsts.md │ ├── jvm-args.md │ ├── mime-types.md │ ├── performance-tuning.md │ ├── proxy-ip.md │ ├── resource-manager-logging.md │ ├── rest-servlet.md │ ├── security │ │ ├── README.md │ │ ├── basic-authentication.md │ │ └── client-cert-authentication.md │ ├── server-home.md │ ├── server-profiles.md │ ├── server-rules │ │ ├── README.md │ │ ├── allowed-static-files.md │ │ ├── baked-in-rules.md │ │ ├── custom-predicates-handlers.md │ │ ├── debugging-server-rules.md │ │ ├── rewrites-map.md │ │ ├── rule-examples.md │ │ └── rule-language.md │ ├── ssl-client-certs.md │ ├── undertow-options.md │ ├── url-rewrites.md │ ├── warmup-urls.md │ └── web.xml-overrides.md ├── debugging-server-starts.md ├── external-web-server.md ├── fusionreactor.md ├── install-lucee-core-lex-files.md ├── manage-servers.md ├── modcfml-support.md ├── multi-engine-support.md ├── multi-site-support │ ├── README.md │ ├── bindings.md │ ├── configuring-sites.md │ ├── defining-sites.md │ ├── multi-site-examples.md │ ├── pretty-diagrams.md │ └── servlet-pass-predicate.md ├── offline-server-starts.md ├── server-logs.md ├── server-processes.md ├── server-scripts.md ├── server-versions.md ├── server.json │ ├── README.md │ ├── packaging-your-server.md │ ├── using-multiple-server.json-files.md │ └── working-with-server.json.md ├── single-server-mode.md ├── start-html-server.md ├── starting-as-a-service.md └── websocket-support.md ├── forgebox-enterprise ├── commands │ ├── README.md │ ├── list.md │ ├── login.md │ ├── register.md │ ├── remove.md │ └── set-default.md ├── introduction.md ├── storage.md └── usage.md ├── getting-started-guide.md ├── helpful-commands ├── README.md ├── ask-and-confirm.md ├── checksums.md ├── code-quality-tools.md └── token-replacements.md ├── ide-integrations ├── README.md ├── sublime-text.md └── visual-studio-code.md ├── overview.md ├── package-management ├── README.md ├── artifacts.md ├── box.json │ ├── README.md │ ├── basic-package-data.md │ ├── dependencies.md │ ├── embedded-server.md │ ├── extended-package-data.md │ ├── installation.md │ ├── package-urls.md │ └── testbox.md ├── code-endpoints │ ├── README.md │ ├── cflib.md │ ├── file.md │ ├── folder.md │ ├── forgebox.md │ ├── gist.md │ ├── git.md │ ├── http-s.md │ ├── jar-via-http.md │ ├── java.md │ ├── lex-via-http.md │ └── s3.md ├── creating-packages │ ├── README.md │ ├── editing-package-properties.md │ └── publishing-lucee-extensions-to-forgebox.md ├── dependencies.md ├── installing-packages │ ├── README.md │ ├── advanced-installation.md │ ├── debug-installation.md │ ├── installation-options.md │ └── installation-path.md ├── managing-version.md ├── package-scripts.md ├── private-packages.md ├── semantic-versioning.md ├── system-modules.md └── updating-packages.md ├── release-history ├── 1.x-versions │ ├── README.md │ └── whats-in-1.0.0.md ├── 2.x-versions │ ├── README.md │ ├── whats-new-in-2.0.0.md │ ├── whats-new-in-2.1.0.md │ ├── whats-new-in-2.1.1.md │ └── whats-new-in-2.2.0.md ├── 3.x-versions │ ├── README.md │ ├── whats-new-in-3.0.0.md │ ├── whats-new-in-3.0.1.md │ ├── whats-new-in-3.1.1.md │ ├── whats-new-in-3.2.0.md │ ├── whats-new-in-3.3.0.md │ ├── whats-new-in-3.4.0.md │ ├── whats-new-in-3.5.0.md │ ├── whats-new-in-3.6.0.md │ ├── whats-new-in-3.7.0.md │ ├── whats-new-in-3.8.0.md │ └── whats-new-in-3.9.0.md ├── 4.x-versions │ ├── README.md │ ├── whats-new-in-4.0.0.md │ ├── whats-new-in-4.1.0.md │ ├── whats-new-in-4.2.0.md │ ├── whats-new-in-4.3.0.md │ ├── whats-new-in-4.4.0.md │ ├── whats-new-in-4.5.0.md │ ├── whats-new-in-4.6.0.md │ ├── whats-new-in-4.7.0.md │ └── whats-new-in-4.8.0.md ├── 5.x-versions │ ├── README.md │ ├── whats-new-in-5.0.0.md │ ├── whats-new-in-5.1.0.md │ ├── whats-new-in-5.1.1.md │ ├── whats-new-in-5.2.0.md │ ├── whats-new-in-5.2.1.md │ ├── whats-new-in-5.3.0.md │ ├── whats-new-in-5.3.1.md │ ├── whats-new-in-5.4.0.md │ ├── whats-new-in-5.4.1.md │ ├── whats-new-in-5.4.2.md │ ├── whats-new-in-5.5.1.md │ ├── whats-new-in-5.5.2.md │ ├── whats-new-in-5.6.0.md │ ├── whats-new-in-5.7.0.md │ ├── whats-new-in-5.8.0.md │ ├── whats-new-in-5.9.0.md │ └── whats-new-in-5.9.1.md ├── 6.x-versions │ ├── README.md │ ├── whats-new-in-6.0.0.md │ ├── whats-new-in-6.1.0.md │ └── whats-new-in-6.2.0.md └── README.md ├── setup ├── README.md ├── common-errors.md ├── download.md ├── installation.md ├── light-and-thin-binaries.md ├── non-oracle-jres.md ├── requirements.md └── upgrading.md ├── task-runners ├── README.md ├── basetask-super-class.md ├── caching-task-runners.md ├── cancel-long-tasks.md ├── downloading-files.md ├── error-handling.md ├── hitting-your-database.md ├── installing-lucee-extensions.md ├── interactive-jobs.md ├── lifecycle-events.md ├── loading-ad-hoc-jars.md ├── loading-ad-hoc-modules.md ├── passing-parameters.md ├── progress-bar.md ├── property-files.md ├── running-other-commands.md ├── running-other-tasks.md ├── sending-e-mail.md ├── shell-integration.md ├── task-anatomy.md ├── task-interactivity.md ├── task-output │ ├── README.md │ ├── printing-columns.md │ ├── printing-tables.md │ └── printing-tree.md ├── task-target-dependencies.md ├── threading-async.md ├── using-parameters.md └── watchers.md ├── testbox-integration ├── README.md ├── test-runner.md └── test-watcher.md └── usage ├── 256-color-support.md ├── README.md ├── a-little-fun.md ├── ad-hoc-command-aliases.md ├── auto-update-checks.md ├── bullet-train-prompt.md ├── command-help.md ├── commands.md ├── default-command-parameters.md ├── environment-variables.md ├── execution ├── README.md ├── cfml-files │ ├── README.md │ └── using-a-db-in-cfml-scripts.md ├── cfml-functions.md ├── exit-codes.md ├── os-binaries.md └── recipes.md ├── foreach-command.md ├── interactive-shell-features.md ├── jq-command.md ├── parameters ├── README.md ├── escaping-special-characters.md ├── expressions.md ├── file-paths.md ├── globbing-patterns.md └── piping-into-commands.md ├── printtable-command.md ├── repl.md ├── sql-command.md ├── system-setting-expansion-namespaces.md ├── system-settings.md ├── tab-completion.md └── watch-command.md /.gitbook/assets/CommandBoxLogo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/CommandBoxLogo.png -------------------------------------------------------------------------------- /.gitbook/assets/FR CLI detail.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/FR CLI detail.png -------------------------------------------------------------------------------- /.gitbook/assets/FR CLI history.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/FR CLI history.png -------------------------------------------------------------------------------- /.gitbook/assets/box_icon (2) (2) (2) (2) (2) (2) (2) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/box_icon (2) (2) (2) (2) (2) (2) (2) (1).png -------------------------------------------------------------------------------- /.gitbook/assets/box_icon (2) (2) (2) (2) (2) (2) (2).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/box_icon (2) (2) (2) (2) (2) (2) (2).png -------------------------------------------------------------------------------- /.gitbook/assets/box_icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/box_icon.png -------------------------------------------------------------------------------- /.gitbook/assets/command_help.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/command_help.png -------------------------------------------------------------------------------- /.gitbook/assets/docker.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/docker.png -------------------------------------------------------------------------------- /.gitbook/assets/embedded_server.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/embedded_server.png -------------------------------------------------------------------------------- /.gitbook/assets/extensbility (1) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/extensbility (1) (1).png -------------------------------------------------------------------------------- /.gitbook/assets/extensbility (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/extensbility (1).png -------------------------------------------------------------------------------- /.gitbook/assets/first_run.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/first_run.png -------------------------------------------------------------------------------- /.gitbook/assets/forgebox-endpoint-default-list (1) (1).gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/forgebox-endpoint-default-list (1) (1).gif -------------------------------------------------------------------------------- /.gitbook/assets/forgebox-endpoint-default-list (1).gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/forgebox-endpoint-default-list (1).gif -------------------------------------------------------------------------------- /.gitbook/assets/forgebox-endpoint-login.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/forgebox-endpoint-login.gif -------------------------------------------------------------------------------- /.gitbook/assets/forgebox-endpoint-register (1).gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/forgebox-endpoint-register (1).gif -------------------------------------------------------------------------------- /.gitbook/assets/forgebox-endpoint-register.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/forgebox-endpoint-register.gif -------------------------------------------------------------------------------- /.gitbook/assets/forgebox-endpoint-remove.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/forgebox-endpoint-remove.gif -------------------------------------------------------------------------------- /.gitbook/assets/forgebox-endpoint-set-default.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/forgebox-endpoint-set-default.gif -------------------------------------------------------------------------------- /.gitbook/assets/global_help.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/global_help.png -------------------------------------------------------------------------------- /.gitbook/assets/heroku.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/heroku.png -------------------------------------------------------------------------------- /.gitbook/assets/image (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (1).png -------------------------------------------------------------------------------- /.gitbook/assets/image (10).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (10).png -------------------------------------------------------------------------------- /.gitbook/assets/image (11).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (11).png -------------------------------------------------------------------------------- /.gitbook/assets/image (12).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (12).png -------------------------------------------------------------------------------- /.gitbook/assets/image (13).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (13).png -------------------------------------------------------------------------------- /.gitbook/assets/image (14) (1) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (14) (1) (1).png -------------------------------------------------------------------------------- /.gitbook/assets/image (14) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (14) (1).png -------------------------------------------------------------------------------- /.gitbook/assets/image (14).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (14).png -------------------------------------------------------------------------------- /.gitbook/assets/image (15) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (15) (1).png -------------------------------------------------------------------------------- /.gitbook/assets/image (15).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (15).png -------------------------------------------------------------------------------- /.gitbook/assets/image (16).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (16).png -------------------------------------------------------------------------------- /.gitbook/assets/image (17).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (17).png -------------------------------------------------------------------------------- /.gitbook/assets/image (18).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (18).png -------------------------------------------------------------------------------- /.gitbook/assets/image (19).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (19).png -------------------------------------------------------------------------------- /.gitbook/assets/image (2) (2) (2) (2) (2) (2) (2) (2) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (2) (2) (2) (2) (2) (2) (2) (2) (1).png -------------------------------------------------------------------------------- /.gitbook/assets/image (2) (2) (2) (2) (2) (2) (2) (2).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (2) (2) (2) (2) (2) (2) (2) (2).png -------------------------------------------------------------------------------- /.gitbook/assets/image (2) (2).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (2) (2).png -------------------------------------------------------------------------------- /.gitbook/assets/image (2).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (2).png -------------------------------------------------------------------------------- /.gitbook/assets/image (20).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (20).png -------------------------------------------------------------------------------- /.gitbook/assets/image (21).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (21).png -------------------------------------------------------------------------------- /.gitbook/assets/image (22).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (22).png -------------------------------------------------------------------------------- /.gitbook/assets/image (23).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (23).png -------------------------------------------------------------------------------- /.gitbook/assets/image (24).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (24).png -------------------------------------------------------------------------------- /.gitbook/assets/image (3).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (3).png -------------------------------------------------------------------------------- /.gitbook/assets/image (4).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (4).png -------------------------------------------------------------------------------- /.gitbook/assets/image (5).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (5).png -------------------------------------------------------------------------------- /.gitbook/assets/image (6).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (6).png -------------------------------------------------------------------------------- /.gitbook/assets/image (7).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (7).png -------------------------------------------------------------------------------- /.gitbook/assets/image (8) (1) (1) (1) (1) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (8) (1) (1) (1) (1) (1).png -------------------------------------------------------------------------------- /.gitbook/assets/image (8) (1) (1) (1) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (8) (1) (1) (1) (1).png -------------------------------------------------------------------------------- /.gitbook/assets/image (8) (1) (1) (2) (2) (2) (2) (2) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (8) (1) (1) (2) (2) (2) (2) (2) (1).png -------------------------------------------------------------------------------- /.gitbook/assets/image (8) (1) (1) (2) (2) (2) (2) (2) (2).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (8) (1) (1) (2) (2) (2) (2) (2) (2).png -------------------------------------------------------------------------------- /.gitbook/assets/image (8) (1) (1) (2) (2) (2) (2) (2).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (8) (1) (1) (2) (2) (2) (2) (2).png -------------------------------------------------------------------------------- /.gitbook/assets/image (8).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (8).png -------------------------------------------------------------------------------- /.gitbook/assets/image (9) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (9) (1).png -------------------------------------------------------------------------------- /.gitbook/assets/image (9).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image (9).png -------------------------------------------------------------------------------- /.gitbook/assets/image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/image.png -------------------------------------------------------------------------------- /.gitbook/assets/in_the_package.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/in_the_package.png -------------------------------------------------------------------------------- /.gitbook/assets/namespace_help.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/namespace_help.png -------------------------------------------------------------------------------- /.gitbook/assets/open_package (2) (2) (2) (2) (2) (2) (2) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/open_package (2) (2) (2) (2) (2) (2) (2) (1).png -------------------------------------------------------------------------------- /.gitbook/assets/open_package (2) (2) (2) (2) (2) (2) (2).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/open_package (2) (2) (2) (2) (2) (2) (2).png -------------------------------------------------------------------------------- /.gitbook/assets/open_package.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/open_package.png -------------------------------------------------------------------------------- /.gitbook/assets/ortussolutions_button (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/ortussolutions_button (1).png -------------------------------------------------------------------------------- /.gitbook/assets/ortussolutions_button.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/ortussolutions_button.png -------------------------------------------------------------------------------- /.gitbook/assets/package_manager.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/package_manager.png -------------------------------------------------------------------------------- /.gitbook/assets/run (1) (1) (1) (1) (2) (2) (2) (2) (2) (2) (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/run (1) (1) (1) (1) (2) (2) (2) (2) (2) (2) (1).png -------------------------------------------------------------------------------- /.gitbook/assets/run (1) (1) (1) (1) (2) (2) (2) (2) (2) (2).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/run (1) (1) (1) (1) (2) (2) (2) (2) (2) (2).png -------------------------------------------------------------------------------- /.gitbook/assets/run.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/run.png -------------------------------------------------------------------------------- /.gitbook/assets/shalom (2) (2) (2) (2) (2) (2) (2) (1).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/shalom (2) (2) (2) (2) (2) (2) (2) (1).jpg -------------------------------------------------------------------------------- /.gitbook/assets/shalom (2) (2) (2) (2) (2) (2) (2).jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/shalom (2) (2) (2) (2) (2) (2) (2).jpg -------------------------------------------------------------------------------- /.gitbook/assets/shalom.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/shalom.jpg -------------------------------------------------------------------------------- /.gitbook/assets/system_tray_server_icons.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/system_tray_server_icons.png -------------------------------------------------------------------------------- /.gitbook/assets/terminal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/terminal.png -------------------------------------------------------------------------------- /.gitbook/assets/the_package.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/the_package.png -------------------------------------------------------------------------------- /.gitbook/assets/versions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/versions.png -------------------------------------------------------------------------------- /.gitbook/assets/welcome (1).png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/welcome (1).png -------------------------------------------------------------------------------- /.gitbook/assets/welcome.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ortus-docs/commandbox-docs/841c2ba959a68ac83b63fbdcaa5b912abfb6108f/.gitbook/assets/welcome.png -------------------------------------------------------------------------------- /config-settings/env-var-overrides.md: -------------------------------------------------------------------------------- 1 | # Env Var Overrides 2 | 3 | Every [Config Setting](./) can be overridden by convention by creating environment variables in the shell where you run `box`. This is idea for CI builds were you want to easily set ForgeBox API keys, or tweak settings for your build. You set set these as actual environment variables or [Java system properties of the CLI](https://commandbox.ortusbooks.com/usage/execution#ad-hoc-java-properties-for-the-cli). 4 | 5 | The var must start with the text `box_config_` and will be followed by the name of the setting. 6 | 7 | ```bash 8 | box_config_colorInDumbTerminal=true 9 | ``` 10 | 11 | For nested settings inside of a struct or array you can use underscores to represent dots. 12 | 13 | ```bash 14 | box_config_endpoints_forgebox_APIToken=my-token-here 15 | ``` 16 | 17 | The overrides are applied using the same mechanism that the `config set` command uses, which means you can also pass JSON directly for complex values. 18 | 19 | ```bash 20 | # JSON which will be parsed 21 | box_config_proxy={ "server" : "localhost", "port": 80 } 22 | ``` 23 | 24 | On OS's like Windows which allow for any manner of special characters, you can provide any string which would also be valid for the `config set` command. Ex: 25 | 26 | ```bash 27 | # dot-delimited keys 28 | box_config_endpoints.forgebox.APIToken=my-token-here 29 | # array indexes too 30 | box_config_foo.bar[baz].bum[1]=test 31 | ``` 32 | 33 | When you provide JSON, the `append` flag will be set to true when adding the configuration to what's already in CommandBox. 34 | 35 | Overridden env vars will not be written to the `CommandBox.json` file and will be lost when box stops. They will also take precedence and override any explicit settings already set. 36 | -------------------------------------------------------------------------------- /config-settings/json-settings.md: -------------------------------------------------------------------------------- 1 | # JSON Settings 2 | 3 | You can customize the way that JSON is formatted when it's written to files such as `server.json` and `box.json` as well as how it displays in the console when using commands such as `server show` and `package show` 4 | 5 | ## JSON.indent 6 | 7 | **string** 8 | 9 | String to use for indenting lines. Defaults to four spaces. 10 | 11 | ```bash 12 | config set JSON.indent=" " 13 | ``` 14 | 15 | ## JSON.lineEnding 16 | 17 | **string** 18 | 19 | String to use for line endings. Defaults to CRLF on Windows and LF on \*nix. Pass the actual character to use, not a placeholder. 20 | 21 | ```bash 22 | config set JSON.lineEnding=`#chr 10` 23 | ``` 24 | 25 | ## JSON.spaceAfterColon 26 | 27 | **boolean** 28 | 29 | Add space after each colon like `"value": true` instead of `"value":true` Defaults to false 30 | 31 | ```bash 32 | config set JSON.spaceAfterColon=true 33 | ``` 34 | 35 | ## JSON.sortKeys 36 | 37 | **string** 38 | 39 | Specify a sort type to sort the keys of json objects: `text` or `textnocase` 40 | 41 | ```bash 42 | config set JSON.sortKeys=textnocase 43 | ``` 44 | 45 | ## JSON.ANSIColors 46 | 47 | **struct** 48 | 49 | A struct of colors to use when displaying JSON in the CLI. You can use any color name from the `system-colors` command or a direct ANSI escape sequence. 50 | 51 | ## JSON.ANSIColors.constant 52 | 53 | **string** 54 | 55 | The color to use for constant values (true/false/null). Defaults to "red". 56 | 57 | ```bash 58 | config set JSON.ANSIColors.constant=PaleTurquoise1 59 | ``` 60 | 61 | ## JSON.ANSIColors.key 62 | 63 | **string** 64 | 65 | The color to use for object key names. Defaults to "blue". 66 | 67 | ```bash 68 | config set JSON.ANSIColors.key=Purple5 69 | ``` 70 | 71 | ## JSON.ANSIColors.number 72 | 73 | **string** 74 | 75 | The color to use for numbers. Defaults to "aqua". 76 | 77 | ```bash 78 | config set JSON.ANSIColors.number=SeaGreen3 79 | ``` 80 | 81 | ## JSON.ANSIColors.string 82 | 83 | **string** 84 | 85 | The color to use for quoted string values. Defaults to "lime". 86 | 87 | ```bash 88 | config set JSON.ANSIColors.string=MistyRose3 89 | ``` 90 | 91 | 92 | 93 | -------------------------------------------------------------------------------- /config-settings/module-settings.md: -------------------------------------------------------------------------------- 1 | # Module Settings 2 | 3 | These settings affect how CommandBox loads modules. 4 | 5 | ## ModulesExternalLocation 6 | 7 | **array** 8 | 9 | You can store CommandBox modules outside of the default installation directory. This may be useful to point to modules you are developing or to keep custom modules around even if CommandBox gets uninstalled. 10 | 11 | ```bash 12 | config set ModulesExternalLocation=[\"/var/my/external/modules\"] 13 | config show ModulesExternalLocation 14 | ``` 15 | 16 | ## modulesInclude 17 | 18 | **array** 19 | 20 | An array of module names to load. Be careful of using this setting as once you set it, no other modules will be loaded which includes all of CommandBox's core modules. 21 | 22 | ```bash 23 | config set modulesInclude=[\"moduleName\",\"anotherModuleName\"] 24 | config show modulesInclude 25 | ``` 26 | 27 | ## ModulesExclude 28 | 29 | **array** 30 | 31 | An array of module names NOT to load. This can be useful when you have an installed module that's erroring on load and preventing CommandBox from starting up. 32 | 33 | ```bash 34 | config set ModulesExclude=[\"moduleName\",\"anotherModuleName\"] 35 | config show ModulesExclude 36 | ``` 37 | 38 | ## modules.\* 39 | 40 | **struct** 41 | 42 | When you install a CommandBox module, it may contain settings that affect how it works. Don't edit the CFML code in the module, instead use the `config set` command to create config settings that will override the module's defaults. The pattern is `modules.moduleName.settingName`. 43 | 44 | ```bash 45 | config set modules.TestModule.mySetting=overridden 46 | config set modules.TestModule.somethingEnabled=false 47 | ``` 48 | 49 | When a module is loaded, the config settings (that exist) for that module are loaded as well. Any time you set a new module setting, that setting will be loaded into memory immediately for that module. 50 | 51 | You can easily see what settings are set for our `TestModule` like so: 52 | 53 | ```bash 54 | config show modules.TestModule 55 | ``` 56 | -------------------------------------------------------------------------------- /config-settings/proxy-settings.md: -------------------------------------------------------------------------------- 1 | # Proxy Settings 2 | 3 | If you need to use CommandBox behind a corporate proxy, these settings will be necessary for it to successfully connect to the Internet. 4 | 5 | ## proxy.server 6 | 7 | **string** 8 | 9 | This is the URL of the proxy server on your network. 10 | 11 | ```bash 12 | config set proxy.server=myProxy.com 13 | config show proxy.server 14 | ``` 15 | 16 | ## proxy.port 17 | 18 | **integer** 19 | 20 | This is the port to connect to on the proxy server. 21 | 22 | ```bash 23 | config set proxy.port=9000 24 | config show proxy.port 25 | ``` 26 | 27 | ## proxy.user 28 | 29 | **string** 30 | 31 | This is the username to connect to the proxy server with, if required. 32 | 33 | ```bash 34 | config set proxy.user=proxyUser 35 | config show proxy.user 36 | ``` 37 | 38 | ## proxy.password 39 | 40 | **string** 41 | 42 | This is the password to connect to the proxy server with, if required. 43 | 44 | ```bash 45 | config set proxy.password=proxyPass 46 | config show proxy.password 47 | ``` 48 | -------------------------------------------------------------------------------- /config-settings/server-settings.md: -------------------------------------------------------------------------------- 1 | # Server Settings 2 | 3 | These settings control how servers start in CommandBox. 4 | 5 | ## server.defaults 6 | 7 | **struct** 8 | 9 | This struct can contain any [setting that is valid in a `server.json` file](../embedded-server/server.json/). These settings are used as global default settings if there is not a corresponding setting provided by the user via a parameter to the `start` command or in the server's `server.json` file. 10 | 11 | ```bash 12 | config set server.defaults.web.rewrites.enable=true 13 | config set server.defaults.openbrowser=false 14 | config set server.defaults.jvm.heapsize=1024 15 | config show server.defaults 16 | ``` 17 | -------------------------------------------------------------------------------- /config-settings/task-runner-settings.md: -------------------------------------------------------------------------------- 1 | # Task Runner Settings 2 | 3 | ## taskCaching 4 | 5 | **boolean** 6 | 7 | Every time you execute a task runner, 8 | 9 | * Lucee template cache is cleared 10 | * WireBox's metadata cache is cleared 11 | * Wirebox's mapping for the CFC is unmapped and remapped 12 | 13 | This ensure changes take affect right away, but can cause issue under load when you have multi-threaded execution of more than one task at the same time. To skip these cache clearing steps on every run for multi-threaded production use, add the following config setting. 14 | 15 | ```bash 16 | config set taskCaching=true 17 | ``` 18 | 19 | The setting defaults to **false**. 20 | -------------------------------------------------------------------------------- /deploying-commandbox/README.md: -------------------------------------------------------------------------------- 1 | # Deploying CommandBox 2 | 3 | CommandBox may also be used in production or continuous deployments, since it allows you to orchestrate your server environment. This eliminates dependency on hardware, and makes your CFML applications more portable, as a whole. 4 | 5 | {% hint style="info" %} 6 | For advanced server configurations, be sure to check out the [`CFConfig` module](https://cfconfig.ortusbooks.com/). 7 | {% endhint %} 8 | 9 | Since the startup of a CommandBox server allows you specify a host and server port, you can easily bind your server to a machine IP address and specify which port it should serve the application on. This allows you to proxy traffic to the application from IIS, Apache, or NGINX and even allows you to serve traffic directly on HTTP port 80 or 443, if you choose. 10 | 11 | Container-based deployments are also supported, with official Docker Images and a buildpack for Heroku/Dokku. 12 | 13 | ![Docker Logo](../.gitbook/assets/docker.png) 14 | 15 | [_Click to learn more._](docker.md) 16 | 17 | ![Heroku Logo](../.gitbook/assets/heroku.png) 18 | 19 | [_Click to learn more._](heroku.md) 20 | 21 | ![Amazon Lightsail](<../.gitbook/assets/image (24).png>) 22 | 23 | [_Click to learn more._](amazon-lightsail.md) 24 | -------------------------------------------------------------------------------- /developing-for-commandbox/README.md: -------------------------------------------------------------------------------- 1 | # Developing For CommandBox 2 | 3 | CommandBox is written in CFML, which puts any CFML developer in a position to easily build upon it for their own needs. CommandBox is not only a CLI tool and collection of pre-built commands, but also an extensible framework for building your own CFML-based automations. The core is modular such that anyone can extend it themselves or via the help of community modules hosted on ForgeBox, or any other installation endpoint. 4 | 5 | ## Modularity 6 | 7 | The unit of re-use in CommandBox is the module. A module is nothing more than a folder containing some settings and code that follows a convention. Modules mean that you can develop your own additions and customizations to the tool without needing to modify the core code. 8 | 9 | [Read about **Developing Modules** here.](modules/) 10 | 11 | ## Custom Commands 12 | 13 | CommandBox's expressive CLI gets its power from commands. You can create your own commands by packaging simple CFCs inside of modules. This is a powerful way to create custom, reusable CFML scripts that interact with the user, automate hard tasks, and can be shared with other developers. Commands are better than stand alone CFML files because they have very well-defined parameters, validation, and WireBox DI. 14 | 15 | [Read about **Developing Commands** here.](commands/) 16 | 17 | ## Event Model 18 | 19 | Customizing the internals of CommandBox is achieved via an event model known as interceptors. What this means is that at pre-defined points in the lifecycle of the shell, command execution, or web server starting, the CLI broadcasts events that you can listen to. This lets you provide custom error handling, special server handling, or modify command output. Interceptors are packaged up in modules and can be combined with custom commands and config settings for fully-configurable shell add-ons. 20 | 21 | [Read about **Developing Interceptors** here.](interceptors/) 22 | 23 | ## Developer Mode 24 | 25 | The `developerMode` setting reloads shell before each command to help testing changes to CommandBox core or modules. 26 | 27 | ``` 28 | config set developerMode=true 29 | ``` 30 | 31 | It will prevent you from needing to use the `reload` command, but it will cause a delay before each command. Don't forget to turn this back off when you're done. 32 | -------------------------------------------------------------------------------- /developing-for-commandbox/commands/aliases.md: -------------------------------------------------------------------------------- 1 | # Aliases 2 | 3 | A command can go by more than one name. For instance, the `dir` command can also be called as `ls`, `ll`, or `directory`. Set a comma-delimited list of aliases in your component declaration like so: 4 | 5 | ```javascript 6 | component aliases="ls,ll,directory" { 7 | } 8 | ``` 9 | 10 | Command aliases don't even have to be in the same namespace. For instance, the `server start` command has an alias of just `start`. This can be very powerful as you can install a command that "overwrites" a built-in command by aliasing itself as that command. 11 | 12 | With power comes responsibility though. Make sure you don't distribute a command that accidentally stomps all over another command. Unless your command name is decidedly unique, it's probably best for most custom commands to use a namespace to avoid conflicts. 13 | -------------------------------------------------------------------------------- /developing-for-commandbox/commands/error-handling.md: -------------------------------------------------------------------------------- 1 | # Error handling 2 | 3 | When a command throws an unhandled exception, any output in its print buffer will be flushed to the screen. Then the error message accompanied by a tag stack will be output to the screen and the user will be returned to the prompt. 4 | 5 | If an unexpected error happens inside a command that is non-recoverable, do not attempt to try/catch it unless you can improve the error message to something more useful. Generally speaking, just let the error bubble up and be handled by CommandBox for consistency and simplicity. 6 | 7 | ## Controlled Errors 8 | 9 | If there are expected situations such as a file not existing, that you know might go wrong, we wholeheartedly recommend checking for these situations and using the `error()` method to alert the user. 10 | 11 | Errors returned from the `error()` method will not contain any stack traces, etc. 12 | 13 | ```javascript 14 | error( "I don't like your tone of voice" ); 15 | ``` 16 | 17 | You can set a detail and an error code as well. The error code will be used as the exit code for the command. 18 | 19 | ```javascript 20 | error( "We're sorry, but happy hour ended 20 minutes ago.", "Sux 2B U", 123 ); 21 | ``` 22 | 23 | The CFML exception that is thrown from the `error()` method will contain the exit code in the `errorcode` part of the cfcatch struct. The Exit code is also available as a system setting called `exitCode`. 24 | 25 | ```bash 26 | > !git status 27 | fatal: not a git repository (or any of the parent directories): .git 28 | Command returned failing exit code [128] 29 | 30 | > echo ${exitCode} 31 | 128 32 | ``` 33 | 34 | ## Verbose Errors in the Shell 35 | 36 | When an unhandled exception happens in the shell, only the tag context is shown. You can enable full stack trace output like so: 37 | 38 | ```bash 39 | config set verboseErrors=true 40 | ``` 41 | 42 | 43 | 44 | -------------------------------------------------------------------------------- /developing-for-commandbox/commands/loading-ad-hoc-jars.md: -------------------------------------------------------------------------------- 1 | # Loading Ad hoc Jars 2 | 3 | If you need to use a 3rd party jar, we recommend you use the extra parameters to the createObject() function, which allows you to specify a list of jars to load from (this is a Lucee-specific feature). Read up on the `context` parameter here: 4 | 5 | {% embed url="http://docs.lucee.org/reference/functions/createobject.html" %} 6 | 7 | There are some scenarios however that don't work. One is if you need to use the `createDynamicProxy()` BIF to create CFC instances that implement Java classes that exist in an ad hoc jar. Lucee currently requires those classes to be loaded by the Lucee system classloader. 8 | 9 | As such, CommandBox gives you a mechanism to load jars into the system class loader that was used to classload Lucee so those classes are available everywhere. This is a much better and portable solution to dropping the jars in the `~/.CommandBox/lib` folder and restarting the shell. 10 | 11 | ## classLoad() 12 | 13 | To load up your custom jars on the fly, call the `classLoad()` method which is available in any custom command or Task Runner. 14 | 15 | ```javascript 16 | classLoad( 'D:/amqp-client-5.1.2.jar' ); 17 | ``` 18 | 19 | You can pass either an array or list of: 20 | 21 | * D**irectories** 22 | * All jar and class files will be loaded from each directory recursively 23 | * **Jar files** 24 | * Each jar file will be loaded 25 | * **Class files** - Each class file will be loaded 26 | 27 | Note, paths need to be absolute when you pass them in! Here's some more examples. 28 | 29 | ```javascript 30 | classLoad( 'C:/myLibs,C:/otherLibs' ); 31 | classLoad( [ 'C:/myLibs', 'C:/otherLibs' ] ); 32 | classLoad( 'C:/myLibs/myLib.jar,C:/otherLibs/other.class' ); 33 | classLoad( [ 'C:/myLibs/myLib.jar', 'C:/otherLibs/other.class' ] ); 34 | ``` 35 | -------------------------------------------------------------------------------- /developing-for-commandbox/commands/shell-integration.md: -------------------------------------------------------------------------------- 1 | # Shell integration 2 | 3 | Your command might need to get information about its environment or perhaps proxy to other commands. Here is a handful of useful methods available to all commands. 4 | 5 | ## getCWD() 6 | 7 | This method will return the Current Working Directory that the user has changed to via the `cd` command. The path will be expanded and fully qualified. 8 | 9 | ## shell.clearScreen() 10 | 11 | This method on the shell object will clear all text off the screen and redraw the CommandBox prompt. 12 | 13 | ## shell.getTermWidth() 14 | 15 | This shell method returns the number of characters wide that the terminal is. Can be useful for outputting long lines and making sure they won't wrap. 16 | 17 | ## shell.getTermHeight() 18 | 19 | This shell method returns the number of characters tall the terminal is. Can be useful for [outputting ASCII art](https://github.com/bdw429s/CommandBox-Image-To-ASCII). 20 | 21 | ## runCommand() 22 | 23 | > **Warning** runCommand() is now deprecated. Please use the [Command() DSL](running-other-commands.md) instead. 24 | 25 | `runCommand()` will run another command from the shell inline and wait for it to complete. Any output from the command you run will be sent to the console. You must pass the command and any parameters in **exactly** as you would enter in the interactive shell which includes escaping any special characters. 26 | 27 | ```javascript 28 | runCommand( 'echo "Greetings planet"' ); 29 | ``` 30 | 31 | If your passing through a value that may or may not need escaping, there is a method in the parser that will help you. 32 | 33 | ```javascript 34 | runCommand( 'echo "#getInstance( 'parser' ).escapeArg( untrustedVariable )#"' ); 35 | ``` 36 | 37 | By default, commands run via `runCommand()` will send their output to the console. It is possible to capture that output for your own purposes. 38 | 39 | ```javascript 40 | // Run echo and capture its output 41 | var result = runCommand( command='echo hello', returnOutput=true ); 42 | // Force it to echo in green text 43 | print.green( result ).toConsole(); 44 | ``` 45 | 46 | > **Note** You won't be able to capture any output that's already flushed directly to the console. 47 | -------------------------------------------------------------------------------- /developing-for-commandbox/commands/using-parameters/dynamic-parameters.md: -------------------------------------------------------------------------------- 1 | # Dynamic Parameters 2 | 3 | Sometimes you have a command that can need an undetermined number of configuration items that all relate to the same thing. CommandBox can accept any number of named or positional parameters, but it can be hard to collect a dynamic and unknown number of parameters. An easy way to handle this is to have the user prefix each grouped parameter name with `something:` like this. 4 | 5 | ``` 6 | doWidget widgetProp:foo=blue widgetProp:bar=seven widgetProp:baz=turkey 7 | ``` 8 | 9 | This will create a single item in the `arguments` scope of your command called `widgetProp` which is a struct and contains the keys `foo`, `bar`, and `baz`. You can loop over the `widgetProp` struct to access the collection in a concise manner. You can have as any of these parameter groups as you want, and a struct will be created for each unique parameter prefix. 10 | 11 | You can omit the prefix entirely and just start a collection of parameters with a colon (`:`) and they will be placed in a struct called `args`. 12 | 13 | ``` 14 | doWidget :foo=blue :bar=seven :baz=turkey 15 | ``` 16 | 17 | And the command might look like this: 18 | 19 | ```javascript 20 | function run( args={} ){ 21 | args.each( function( k, v ) { 22 | print.line( '#k# has a value of #v#.' ); 23 | } ); 24 | } 25 | ``` 26 | 27 | Which, given the parameters shown above, would output this: 28 | 29 | ``` 30 | foo has a value of blue. 31 | bar has a value of seven. 32 | baz has a value of turkey. 33 | ``` 34 | 35 | To escape a literal colon (`:`) in a parameter name, put a backslash in front of it: 36 | 37 | ```bash 38 | server set foo\:bar=baz 39 | ``` 40 | 41 | which will create a literal key of `foo:bar.`\ 42 | -------------------------------------------------------------------------------- /developing-for-commandbox/commands/watchers-1.md: -------------------------------------------------------------------------------- 1 | # Watchers 2 | 3 | CommandBox has a powerful utility that can be used to watch a folder of files for changes and fire arbitrary code when changes happen. The utility will block execution of the command until the user stops it with `Ctrl+C`. To use a watcher in your command, there is a method called `watch()` in the base command class that you can call. It has a nice DSL of chainable methods to configure it. 4 | 5 | ``` 6 | watch() 7 | .paths( '**.cfc' ) 8 | .inDirectory( getCWD() ) 9 | .withDelay( 5000 ) 10 | .onChange( function() { 11 | 12 | print.line( 'Something changed!' ); 13 | command( 'testbox run' ) 14 | .run(); 15 | 16 | } ) 17 | .start(); 18 | ``` 19 | 20 | Here's a rundown of the methods used above in the DSL. 21 | 22 | * **paths( ... )** - Receives a comma-delimited list of globbing patterns to watch for changes. (defaults to `**`) Note that the "paths" here work more like `.gitignore` entries and less like bash paths. Specifically: 23 | * A path with a leading slash (or backslash), will be evaluated relative to the current working directory. E.g. `watch /foo` will only watch files in the directory at `./foo`, but not in directories like `./bar/foo`. 24 | * A path without a leading slash (or backslash) will be applied as a glob filter to _all files_ within the current working directory. E.g. `watch foo` will result in the entire working directory being watched, but only files matching the glob `**foo` will be processed. 25 | 26 | If your watcher seems slow, unresponsive, or is failing to notice some file change events, it is likely that you have it watching too many files. Try specifying more specific paths to the files you want to process, and use leading slashes in your arguments to avoid watching all files in the current working directory. 27 | * **inDirectory( ... )** - Set the base directory that the file globs are relative to. (defaults to current working directory) 28 | * **withDelay( ... )** - Set the number of milliseconds between polling the file system. (defaults to 500 ms) 29 | * **onChange( ... )** - Pass a closure to be executed when a change has occurred. 30 | * **start()** - Starts the watcher. Always call this at the end of the DSL chain 31 | -------------------------------------------------------------------------------- /developing-for-commandbox/commands/watchers.md: -------------------------------------------------------------------------------- 1 | # Watchers 2 | 3 | CommandBox has a powerful utility that can be used to watch a folder of files for changes and fire arbitrary code when changes happen. The utility will block execution of the command until the user stops it with `Ctrl+C`. To use a watcher in your command, there is a method called `watch()` in the base command class that you can call. It has a nice DSL of chainable methods to configure it. 4 | 5 | ```javascript 6 | watch() 7 | .paths( '**.cfc' ) 8 | .excludePaths( '/config/Coldbox.cfc,/config/WireBox.cfc' ) 9 | .inDirectory( getCWD() ) 10 | .withDelay( 5000 ) 11 | .onChange( function() { 12 | 13 | print.line( 'Something changed!' ); 14 | command( 'testbox run' ) 15 | .run(); 16 | 17 | } ) 18 | .start(); 19 | ``` 20 | 21 | Here's a rundown of the methods used above in the DSL. 22 | 23 | * **paths( ... )** - Receives a comma-delimited list of globbing patterns to watch for changes. (defaults to `**`) 24 | * **inDirectory( ... )** - Set the base directory that the file globs are relative to. (defaults to current working directory) 25 | * **withDelay( ... )** - Set the number of milliseconds between polling the file system. (defaults to 500 ms) 26 | * **onChange( ... )** - Pass a closure to be executed when a change has occurred. 27 | * **start()** - Starts the watcher. Always call this at the end of the DSL chain 28 | -------------------------------------------------------------------------------- /developing-for-commandbox/interceptors/README.md: -------------------------------------------------------------------------------- 1 | # Interceptors 2 | 3 | Interceptors are a powerful event-driven model inside CommandBox that allows you to listen to broadcasts from within the core code to respond to events and even influence execution. Interceptors are packaged within CommandBox Modules and can be for your own use, just debugging, or to share with the world. 4 | 5 | To create a simple interceptor, re-create the simple folder structure below inside your CommandBox installation directory. 6 | 7 | ``` 8 | ~/.CommandBox/cfml/modules 9 | +-- myModule/ 10 | |-- ModuleConfig.cfc 11 | +-- interceptors/ 12 | +-- MyInterceptor.cfc 13 | ``` 14 | 15 | ## Creating An Interceptor 16 | 17 | An interceptor is a CFC that has one or more methods whose names match the name of an interception point that is broadcast. Interceptors are packaged within CommandBox modules. When the module is loaded, the InterceptorService will register your interceptor and take care of calling it when necessary. 18 | 19 | Here is an example of an interceptor. It listens to the `postCommand` event and upper cases all output from the command before it is returned to the console. It also listens to `onException` to perform some additional error processing. 20 | 21 | `MyInterceptor.cfc` 22 | 23 | ```javascript 24 | component { 25 | 26 | // This runs after every command execution 27 | function postCommand( interceptData ) { 28 | // Overwrite the results with an upper case version of itself 29 | interceptData.results = ucase( interceptData.results ); 30 | } 31 | 32 | // This runs after every error 33 | function onException( interceptData ) { 34 | // Write the last exception to a file 35 | fileWrite( '/commandbox-home/logs/lastError.txt', serializeJSON( interceptData.exception ) ); 36 | } 37 | 38 | } 39 | ``` 40 | 41 | ## Registering An Interceptor 42 | 43 | Now that we have our interceptor above, how do we register it? This code in our module's config file registers the interceptor so it will listen to the announcements it has declared. 44 | 45 | `ModuleConfig.cfc` 46 | 47 | ```javascript 48 | component{ 49 | function configure(){ 50 | 51 | // Declare our interceptors to listen 52 | interceptors = [ 53 | { class='#moduleMapping#.interceptors.MyInterceptor' } 54 | ]; 55 | 56 | } 57 | } 58 | ``` 59 | -------------------------------------------------------------------------------- /developing-for-commandbox/interceptors/core-interception-points/README.md: -------------------------------------------------------------------------------- 1 | # Core Interception Points 2 | 3 | Here is a list of all the core interception points in CommandBox that you can listen to. Some have `interceptData` that comes along with them, while others don't. Remember, the `interceptData` struct is passed by reference. This means modifying any values directly in that struct will affect how processing continues afterwards inside of CommandBox where those values are used. 4 | 5 | Click a category for more information. 6 | 7 | * [**CLI Lifecycle**](cli-lifecycle.md) 8 | * onCLIStart 9 | * onCLIExit 10 | * onSystemSettingExpansion 11 | * onConfigSettingSave 12 | * onEndpointLogin 13 | * [**Command Execution Lifecycle**](command-execution-lifecycle.md) 14 | * preCommand 15 | * preCommandParamProcess 16 | * postCommand 17 | * prePrompt 18 | * preProcessLine 19 | * postProcessLine 20 | * [**Module Lifecycle**](module-lifecycle.md) 21 | * preModuleLoad 22 | * postModuleLoad 23 | * preModuleUnLoad 24 | * postModuleUnload 25 | * [**Server Lifecycle**](server-lifecycle.md) 26 | * preServerStart 27 | * onServerStart 28 | * onServerInstall 29 | * onServerInitialInstall 30 | * onServerStop 31 | * preServerForget 32 | * postServerForget 33 | * [**Error Handling**](error-handling.md) 34 | * onException 35 | * [**Package Lifecycle**](package-lifecycle.md) 36 | * preInstall 37 | * onInstall 38 | * postInstall 39 | * preUninstall 40 | * postUninstall 41 | * preInstallAll 42 | * postInstallAll 43 | * preVersion 44 | * postVersion 45 | * prePublish 46 | * postPublish 47 | * preUnpublish 48 | * postUnpublish 49 | * onRelease 50 | -------------------------------------------------------------------------------- /developing-for-commandbox/interceptors/core-interception-points/cli-lifecycle.md: -------------------------------------------------------------------------------- 1 | # CLI Lifecycle 2 | 3 | ## onCLIStart 4 | 5 | Announced when shell first starts, but before any commands are run or output has been flushed to the console. 6 | 7 | **interceptData** 8 | 9 | * `shellType` - The string `interactive` if starting the interactive shell, or `command` if running a one-off command and exiting 10 | * `args` - An array of arguments provided from the OS when `box` was executed. 11 | * `banner` - A string containing the CommandBox banner text that displays when in interactive mode. 12 | 13 | This fires every time the `reload` command runs and a fresh shell is created. 14 | 15 | ## onCLIExit 16 | 17 | Announced right before the shell exits and control is returned back to the OS. This fires every time the `reload` command runs right before the shell is destroyed and re-created. 18 | 19 | ## onSystemSettingExpansion 20 | 21 | Announced every time a system setting in the format of `${something}` is expanded. Any interceptor listening can provide an expanded value. 22 | 23 | **interceptData** 24 | 25 | * **setting** - The name of the setting with the default value removed. 26 | * **defaultValue** - The text after the final `:` or an empty string if there is no default provided 27 | * **resolved** - Set this to `true` if your interceptor expands the value and return `true` from your interceptor method so CommandBox stops the interceptor chain. 28 | * **context** - A struct of values if this system setting is being expanded in the context of a JSON file. 29 | 30 | ## onConfigSettingSave 31 | 32 | Announced every time a Config Setting is added, removed, or updated. 33 | 34 | **interceptData** 35 | 36 | * **configFilePath**- Full path to the `CommandBox.json` file 37 | * **configSettings**- Struct of current config settings 38 | 39 | ## onEndpointLogin 40 | 41 | Announced any time a user either logs into ForgeBox (`forgebox login`) or switches users (`forgebox use`) 42 | 43 | **interceptData** 44 | 45 | * **endpointName** - Name of endpoint logged into 46 | * **username** - Username that was logged into 47 | * **endpoint** - Endpoint CFC instance 48 | * **APIToken** - API Token of user that logged in 49 | -------------------------------------------------------------------------------- /developing-for-commandbox/interceptors/core-interception-points/error-handling.md: -------------------------------------------------------------------------------- 1 | # Error Handling 2 | 3 | ## onException 4 | 5 | Announced any time an unhandled exception is thrown. 6 | 7 | **interceptData** 8 | 9 | * `exception` - Error struct 10 | -------------------------------------------------------------------------------- /developing-for-commandbox/interceptors/core-interception-points/module-lifecycle.md: -------------------------------------------------------------------------------- 1 | # Module Lifecycle 2 | 3 | ## preModuleLoad 4 | 5 | Announced before each module that is loaded. 6 | 7 | **interceptData** 8 | 9 | * `moduleLocation` - Path to the module 10 | * `moduleName` - Name of the module 11 | 12 | ## postModuleLoad 13 | 14 | Announced after each module that is loaded. 15 | 16 | **interceptData** 17 | 18 | * `moduleLocation` - Path to the module 19 | * `moduleName` - Name of the module 20 | * `moduleConfig` - Struct representing the configuration data for the module. 21 | 22 | ## preModuleUnLoad 23 | 24 | Announced before each module that is unloaded. 25 | 26 | **interceptData** 27 | 28 | * `moduleName` - Name of the module 29 | 30 | ## postModuleUnload 31 | 32 | Announced after each module that is unloaded. 33 | 34 | **interceptData** 35 | 36 | * `moduleName` - Name of the module 37 | -------------------------------------------------------------------------------- /developing-for-commandbox/interceptors/custom-interception-points.md: -------------------------------------------------------------------------------- 1 | # Custom Interception Points 2 | 3 | You have the ability to create your own interception points on top of the core ones in CommandBox. This can be handy to employ your own event listener model within a module-- which could be comprised of multiple models and commands. Interceptors that listen to custom interception points work the exact same as interceptors that listen to core interception points. In fact, the same interceptor file can listen to both. 4 | 5 | ## Register 6 | 7 | To register your custom interception point with InterceptorService, place the following config in your module's `ModuleConfig.cfc`. This module is registering a custom interception point called `onCustomEvent`. 8 | 9 | ```javascript 10 | component{ 11 | 12 | function configure(){ 13 | 14 | interceptorSettings = { 15 | customInterceptionPoints = 'onCustomEvent' 16 | }; 17 | 18 | } 19 | } 20 | ``` 21 | 22 | ## Announce 23 | 24 | It's up to you to decide when to announce this event and what intercept data you want to provide to it. To announce, use the `announceInterception` method in the InterceptorService. Here's a model that shows how: 25 | 26 | ```javascript 27 | component{ 28 | property name="InterceptorService" inject="InterceptorService"; 29 | 30 | function doSomethingAmazing(){ 31 | 32 | interceptorService.announceInterception( 33 | state='onCustomEvent', 34 | interceptData={ 35 | data='foo', 36 | moreData='bar' 37 | } 38 | ); 39 | 40 | } 41 | } 42 | ``` 43 | -------------------------------------------------------------------------------- /developing-for-commandbox/modules/configuration/README.md: -------------------------------------------------------------------------------- 1 | # Configuration 2 | 3 | The configuration for a module is contained within in the `ModuleConfig.cfc` that lives in the root folder. Here's an overview of the options for configuring your module. 4 | 5 | ```javascript 6 | component{ 7 | // Module Properties 8 | this.autoMapModels = true; 9 | this.modelNamespace = "test"; 10 | this.cfmapping = "test"; 11 | this.dependencies = [ "otherModule", "coolModule" ]; 12 | 13 | function configure(){ 14 | 15 | // Settings for my module 16 | settings = { 17 | mySetting = 'isCool', 18 | settingsCanBe = [ 19 | 'complex', 20 | 'values' 21 | ] 22 | }; 23 | 24 | // Declare some interceptors to listen 25 | interceptors = [ 26 | { 27 | class='#moduleMapping#.interceptors.TestInterceptor' 28 | } 29 | ]; 30 | 31 | // Ad-hoc interception events I will announce myself 32 | interceptorSettings = { 33 | customInterceptionPoints = '' 34 | }; 35 | 36 | // Manually map some models 37 | binder.map( 'foo' ).to( '#moduleMapping#.com.foo.bar' ); 38 | 39 | } 40 | 41 | // Runs when module is loaded 42 | function onLoad(){ 43 | log.info('Module loaded successfully.' ); 44 | } 45 | 46 | // Runs when module is unloaded 47 | function onUnLoad(){ 48 | log.info('Module unloaded successfully.' ); 49 | } 50 | 51 | // An interceptor that listens for every command that's run. 52 | function preCommand( interceptData ){ 53 | // I just intercepted ALL Commands in the CLI 54 | log.info('The command executed is #interceptData.CommandInfo.commandString#'); 55 | } 56 | 57 | } 58 | ``` 59 | -------------------------------------------------------------------------------- /developing-for-commandbox/modules/configuration/lifecycle-methods.md: -------------------------------------------------------------------------------- 1 | # Lifecycle Methods 2 | 3 | Every module follows a sequence of steps when it is loaded and unloaded. Modules are automatically loaded for you when CommandBox starts up, but here are some ways for a module to affect how it loads. 4 | 5 | ## Life-cycle Events 6 | 7 | There are two life-cycle callback events you can declare in your `ModuleConfig.cfc`: 8 | 9 | * `onLoad()` - Called when the module is loaded and activated 10 | * `onUnLoad()` - Called when the module is unloaded from memory 11 | 12 | This gives you great hooks for you to do bootup and shutdown procedures for this specific module. 13 | 14 | ```javascript 15 | function onLoad(){ 16 | log.info('Module loaded successfully.' ); 17 | } 18 | 19 | function onUnLoad(){ 20 | log.info('Module unloaded successfully.' ); 21 | } 22 | ``` 23 | 24 | ## Custom Events 25 | 26 | The `ModuleConfig.cfc` object itself is an interceptor so you can declare all of the CLI's interception points in the configuration object and they will be registered as interceptors. 27 | 28 | ```javascript 29 | function preCommand( interceptData ){ 30 | // I just intercepted ALL Commands in the CLI 31 | log.info('The command executed is #interceptData.CommandInfo.commandString#'); 32 | } 33 | ``` 34 | -------------------------------------------------------------------------------- /developing-for-commandbox/modules/configuration/public-properties.md: -------------------------------------------------------------------------------- 1 | # Public Properties 2 | 3 | You can control how CommandBox loads your module by setting optional settings in the `this` scope. 4 | 5 | * `this.autoMapModels` - Will automatically map all model objects under the models folder in WireBox using `@modulename` as part of the alias. 6 | * `this.modelNamespace` - The name of the namespace to use when registering models in WireBox. Defaults to name of the module. 7 | * `this.cfmapping` - The CF mapping that will be registered for you that points to the root of the module. Defaults to name of the module. 8 | * `this.disabled` - You can manually disable a module from loading and registering. 9 | * `this.dependencies` - An array of dependent module names. All dependencies will be registered and activated FIRST before the module declaring them 10 | 11 | ```javascript 12 | component{ 13 | // Module Properties 14 | this.autoMapModels = true; 15 | this.modelNamespace = "test"; 16 | this.cfmapping = "test"; 17 | this.dependencies = [ "otherModule", "coolModule" ]; 18 | 19 | function configure(){} 20 | } 21 | ``` 22 | -------------------------------------------------------------------------------- /developing-for-commandbox/modules/installation-and-locations.md: -------------------------------------------------------------------------------- 1 | # Installation and Locations 2 | 3 | A module is nothing more than a folder that contains a `ModuleConfig.cfc` file. The only requirement for that CFC is that it contains a method called `configure()`. Modules can also contain models, interceptors, commands, and pretty much anything else you want to stick in them. As long as they contain a `box.json` in their root, they are also a package, which means they are self-describing, can install dependencies, and can be installed via the `install` command. 4 | 5 | ## Locations 6 | 7 | CommandBox has two default `modules` directories. 8 | 9 | * `~/.CommandBox/cfml/system/modules` 10 | * `~/.CommandBox/cfml/modules` 11 | 12 | The first is for system modules so you shouldn't need to touch it. All the built-in commands are in those modules, so feel free to check out how they work. All user-installed modules are in the second folder. The `cfml` folder is the "root" of the CommandBox installation, so there will also be a `box.json` created in that folder once you start installing modules via the `install` command. 13 | 14 | ## Installation 15 | 16 | The first way to create a module is to manually create a folder in the `~/.CommandBox/cfml/modules` directory and place your `ModuleConfig.cfc` inside of it. This is the process described in the guide on [creating your first module](./). 17 | 18 | If you have a package of type `commandbox-modules` locally, in a Git repo, or in Forgebox, you can install from any working directory. When CommandBox sees the package type, it will change the installation directory to be the user modules folder. 19 | 20 | ```bash 21 | install /path/to/module 22 | install githubuser/modulerepo 23 | install forgebox-module-slug 24 | ``` 25 | -------------------------------------------------------------------------------- /developing-for-commandbox/modules/linking-modules.md: -------------------------------------------------------------------------------- 1 | # Linking Modules 2 | 3 | CommandBox allows you to link a module directly into the CommandBox core so that you can use the module as though it's installed but without having two copies of the code. To do this, `cd` to the root of the module you want to link into CommandBox. 4 | 5 | ```bash 6 | cd /path/to/my/cool/module 7 | package link 8 | ``` 9 | 10 | This will create a symlink in the core CommandBox modules directory to your package and reload the shell for you so you can immediately test it out. Any further code changes you make can be tested by running the `reload` command again. 11 | 12 | ## Unlinking 13 | 14 | When you are done testing, you can remove the link by running the `package unlink` command from the root of the module you've been developing on. 15 | 16 | ```bash 17 | cd /path/to/my/cool/module 18 | package unlink 19 | ``` 20 | 21 | This will remove the symlink for you. 22 | -------------------------------------------------------------------------------- /developing-for-commandbox/modules/user-settings.md: -------------------------------------------------------------------------------- 1 | # User Settings 2 | 3 | The defaults for a module is stored in a `settings` struct in the `ModuleConfig.cfc` for that module. However, users can override those settings without needing to touch the core module code. This is made possible by special namespace in the CommandBox config settings called `modules`. 4 | 5 | Consider the following module settings: 6 | 7 | `/modules/TestModule/ModuleConfig.cfc` 8 | 9 | ```javascript 10 | component{ 11 | function configure(){ 12 | settings = { 13 | mySetting = 'isCool', 14 | somethingEnabled = true 15 | }; 16 | } 17 | } 18 | ``` 19 | 20 | The following `config set` commands will create config settings that override those. The pattern is `modules.moduleName.settingName`. 21 | 22 | ```bash 23 | config set modules.TestModule.mySetting=overridden 24 | config set modules.TestModule.somethingEnabled=false 25 | ``` 26 | 27 | When a module is loaded, the config settings (that exist) for that module are also loaded and overwrite the defaults from `ModuleConfig.cfc`. You can easily see what settings are set for our `TestModule` like so: 28 | 29 | ```bash 30 | config show modules.TestModule 31 | ``` 32 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/README.md: -------------------------------------------------------------------------------- 1 | # Configuring Your Server 2 | 3 | CommandBox allows you full control over the servers you start. This includes the port and host, custom JVM args, URL rewriting, web aliases, custom error pages, and custom welcome files. 4 | 5 | ## Ways to provide configuration 6 | 7 | Configuration can be set at several different levels: 8 | 9 | 1. Passed as parameters to the `server start` command 10 | 2. Stored in a `server.json` file for that server 11 | 3. Global defaults in the `server.defaults` config setting 12 | 4. Internal defaults from the `ServerService` 13 | 14 | Settings will be used in that order. Also, any parameters passed to the `start` command will automatically be saved to your `server.json` file unless you pass the `--noSaveSettings` flag. 15 | 16 | ## File path handling 17 | 18 | A lot of settings used to start a server involve file paths. Paths starting with a drive letter like `C:/`, a UNC network path like `\\`, or a leading slash like `/` are considered absolute paths and will not be expanded. Try to avoid absolute paths if you want to make your server config portable. 19 | 20 | Paths that start with a file/folder name like `foo/bar.jar` or `../../lib/my.jar` are relative and the root folder that they are relative to depends on where there are specified. 21 | 22 | * If the path is passed as a parameter to the start command, the path is relative to the current working directory 23 | * If the path is in the `server.json` file, it is relative to the folder containing the JSON file. (Remember the `server.json` doesn't have to be in the web root!) 24 | * If the path is in a global `server.defaults` config setting, it is relative to the web root of the server. 25 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/ad-hoc-java-system-properties.md: -------------------------------------------------------------------------------- 1 | # Ad-Hoc Java System Properties 2 | 3 | You've always been able to add ad-hoc Java system properties for a server in your `server.json` via `jvm.args` in the format of `-Dfoo=bar`. There is also a top-level struct that is more readable which does the same thing: 4 | 5 | ```json 6 | { 7 | "jvm" : { 8 | "properties" : { 9 | "foo" : "bar baz", 10 | "java.awt.headless" : "true" 11 | } 12 | } 13 | ``` 14 | 15 | No additional quoting or escaping is needed for spaces or special characters when using this method. 16 | 17 | Set these programmatically like so: 18 | 19 | ```bash 20 | server set jvm.properties.java.awt.headless=true 21 | ``` 22 | 23 | Or set them globally for all servers in your config setting server defaults. 24 | 25 | ```bash 26 | config set server.defaults.jvm.properties.java.awt.headless=true 27 | ``` 28 | 29 | Keys will be merged, giving precedence to the `server.json` values. 30 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/adding-custom-libs.md: -------------------------------------------------------------------------------- 1 | # Adding Custom Libs 2 | 3 | If you have custom jar files that you want to be available to a server, we recommend you use the `this.javaSettings` functionality in your `Application.cfc` to load those jars. If that isn't an option for you, or you want to include libs for a JDBC drivers then we offer a feature for you to specify a list of directories for which CommandBox will load jars from. This prevents you from worrying about getting your jars inside the `WEB-INF/lib` which starts fresh anytime you forget a server. 4 | 5 | To load in your jar files, the first method is to use the `libDirs` parameter to the `server start` command. 6 | 7 | ``` 8 | server start libDirs=path/to/libs,another/path/to/libs 9 | ``` 10 | 11 | And the way to specify this in a portable manner in your \`server.json\` is like so: 12 | 13 | ``` 14 | server set app.libDirs=path/to/libs,another/path/to/libs 15 | server start 16 | ``` 17 | 18 | Remember, paths to the `start` command are relative to your current working directory and paths in your `server.json` file are relative to the folder that the `server.json` file lives in. Absolute paths work the same everywhere. 19 | 20 | ## Global Custom Libs 21 | 22 | Have a bunch of servers and they ALL need the same jars, you can add your \`libDirs\` to the global server defaults config settings. Your global lib directories won't be overwritten by server-level config dirs, but instead appended to. Relative paths in your config settings are relative to the respective web root of the server. CommandBox will also ignore missing lib dirs to give you some flexibility in this. 23 | 24 | ``` 25 | config set servers.defaults.app.libDirs=/path/to/global/libs 26 | ``` 27 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/aliases.md: -------------------------------------------------------------------------------- 1 | # Aliases 2 | 3 | CommandBox allows you to create web aliases for the web server that are similar to virtual directories. The alias path is relative to the folder the `server.json` lives in, but can point to any folder on the hard drive. Aliases can be used for static or CFM files. 4 | 5 | {% hint style="info" %} 6 | Remember, relative paths configured in a JSON file (whether `server.json`, or `.site.json`, etc) will be resolved relative to the folder that the JSON file lives in! 7 | {% endhint %} 8 | 9 | To configure aliases for your server, create an object under `web` called `aliases`. The keys are the web-accessible virtual paths and the corresponding values are the relative or absolute path to the folder the alias points to. 10 | 11 | Here's what your `server.json` might look like. 12 | 13 | ```javascript 14 | { 15 | "web" : { 16 | "aliases" : { 17 | "/foo" : "bar", 18 | "/js" : "C:\static\shared\javascript" 19 | } 20 | } 21 | } 22 | ``` 23 | 24 | Here's how to create aliases from the `server set` command: 25 | 26 | ``` 27 | server set web.aliases./foo = bar 28 | server set web.aliases./js = C:\static\shared\javascript 29 | ``` 30 | 31 | > **info** On Adobe ColdFusion servers, .cfm files will be run automatically from inside an aliases directory. On Railo and Lucee servers, you'll need to create a CF mapping that maps the alias name and path for .cfm files to work. 32 | 33 | {% hint style="info" %} 34 | For [Multi-Site](../multi-site-support/), web alias settings can be configured on a per-site basis in the `sites` object of the `server.json` or in a `.site.json` file. 35 | {% endhint %} 36 | 37 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/bindings/open-browser-url.md: -------------------------------------------------------------------------------- 1 | # Open Browser URL 2 | 3 | ## Customize URL that opens for server 4 | 5 | By default, CommandBox will open your browser with the host and port of the server. You can customize the exact URL that opens. This setting will be appended to the current host and port. 6 | 7 | ``` 8 | server set openBrowserURL=/bar.cfm 9 | ``` 10 | 11 | Or you can completely override the URL if your setting starts with `http://`. 12 | 13 | ``` 14 | server set openBrowserURL=http://127.0.0.1:59715/test.cfm 15 | ``` 16 | 17 | {% hint style="info" %} 18 | For [Multi-Site](../../multi-site-support/), the openBrowserURL can be configured on a per-site basis in the `sites` object of the `server.json` or in a `.site.json` file. The browser will not open automatically, but this setting will control the options in the tray menu and the `server open` command. 19 | {% endhint %} 20 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/bindings/ssl-client-certs.md: -------------------------------------------------------------------------------- 1 | # Legacy SSL Client Cert syntax 2 | 3 | {% hint style="danger" %} 4 | The syntax on this page is deprecated. It will still work for the foreseeable future, but we recommend using the [new `bindings` object](./) instead which is much more powerful and allows multiple bindings. 5 | {% endhint %} 6 | 7 | {% code title="server.json" %} 8 | ```javascript 9 | { 10 | "web" : { 11 | "ssl" : { 12 | "enable" : true, 13 | "clientCert" : { 14 | "mode" : "Requested", 15 | "CACertFiles" : "rootCA.cer,anotherRootCA.cer", 16 | // OR... 17 | "CACertFiles" : [ 18 | "rootCA.cer", 19 | "anotherRootCA.cer" 20 | ], 21 | "CATrustStoreFile' : "cacerts", 22 | "CATrustStorePass' : "changeit" 23 | } 24 | } 25 | } 26 | } 27 | ``` 28 | {% endcode %} 29 | 30 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/custom-error-pages.md: -------------------------------------------------------------------------------- 1 | # Custom Error Pages 2 | 3 | You can customize the error page that CommandBox servers return. You can have a setting for each status code including a default error page to be used if no other setting applies. 4 | 5 | Create an `errorPages` object inside the `web` object in your `server.json` where each key is the status code integer or the word `default` and the value is a relative (to the web root) path to be loaded for that status code. 6 | 7 | This is what you `server.json` might look like: 8 | 9 | ``` 10 | { 11 | "web" : { 12 | "errorPages" : { 13 | "404" : "/path/to/404.html", 14 | "500" : "/path/to/500.html", 15 | "default" : "/path/to/default.html" 16 | } 17 | } 18 | } 19 | ``` 20 | 21 | You can set error pages via the `server set` command like this: 22 | 23 | ``` 24 | server set web.errorPages.404=/missing.htm 25 | ``` 26 | 27 | {% hint style="info" %} 28 | For [Multi-Site](../multi-site-support/), custom error page settings can be configured on a per-site basis in the `sites` object of the `server.json` or in a `.site.json` file. 29 | {% endhint %} 30 | 31 | ## Accessing error variables 32 | 33 | If your error page points to a CFM file, you can get access to the original path being accessed for 404s and the error that was thrown for 500s. To see all the request headers that are available, use the following snippet of code: 34 | 35 | ```javascript 36 | req = getPageContext().getRequest(); 37 | names = req.getAttributeNames(); 38 | while( names.hasMoreElements() ) { 39 | name = names.nextElement(); 40 | writeOutput( name & ' = ' & req.getAttribute( name ) & '
' ); 41 | } 42 | ``` 43 | 44 | An example of getting the original missing path in a 404 in Lucee would look like this: 45 | 46 | ```javascript 47 | var originalPath = getPageContext().getRequest().getAttribute( "javax.servlet.error.request_uri" ); 48 | ``` 49 | 50 | In Adobe ColdFusion, you can access `ServletRequest` Attributes directly via the CGI scope: 51 | 52 | ```javascript 53 | var originalPath = cgi[ 'javax.servlet.error.request_uri' ]; 54 | ``` 55 | 56 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/custom-welcome-files.md: -------------------------------------------------------------------------------- 1 | # Welcome Files 2 | 3 | The default welcome files are the usual index.cfm, index.htm, index.html, etc but you can override this with the `welcomeFiles` setting in your `server.json` by providing a comma-delimited list of files that you would like CommandBox to look for when a user hits a directory on a running server. 4 | 5 | ``` 6 | server set web.welcomeFiles='go.cfm,main.cfm,index.html' 7 | ``` 8 | 9 | This setting is a complete override of the defaults, so you need to specify the full list. 10 | 11 | ## Directory Browsing 12 | 13 | By default, a CommandBox server will not show the contents of a directory that doesn't have an index file. You can enable directory browsing for a single server with 14 | 15 | ```bash 16 | server set web.directoryBrowsing=true 17 | ``` 18 | 19 | And you can enable it for all servers by default with 20 | 21 | ```bash 22 | config set server.defaults.web.directoryBrowsing=true 23 | ``` 24 | 25 | {% hint style="info" %} 26 | For [Multi-Site](../multi-site-support/), Welcome File settings can be configured on a per-site basis in the `sites` object of the `server.json` or in a `.site.json` file. 27 | {% endhint %} 28 | 29 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/env-var-overrides.md: -------------------------------------------------------------------------------- 1 | # server.json Env Var overrides 2 | 3 | Every [server setting](../server.json/) can be overridden by convention by creating environment variables in the shell where you run `box`. This is idea for CI builds were you want to easily set ports, or tweak settings for your build. You set set these as actual environment variables or [Java system properties of the CLI](https://commandbox.ortusbooks.com/usage/execution#ad-hoc-java-properties-for-the-cli). 4 | 5 | The var must start with the text `box_server_` and will be followed by the name of the setting. 6 | 7 | ```bash 8 | box_server_profile=production 9 | ``` 10 | 11 | For nested settings inside of a struct or array you can use underscores to represent dots. 12 | 13 | ```bash 14 | box_server_web_http_port=8080 15 | ``` 16 | 17 | The overrides are applied using the same mechanism that the `config set` command uses, which means you can also pass JSON directly for complex values. 18 | 19 | ```bash 20 | # JSON which will be parsed 21 | box_server_web_ssl={ "enabled" : true, "port": 443 } 22 | ``` 23 | 24 | On OS's like Windows which allow for any manner of special characters, you can provide any string which would also be valid for the `config set` command. Ex: 25 | 26 | ```bash 27 | # dot-delimited keys 28 | box_server_web.http.port=8080 29 | # array indexes too 30 | box_server_web_rules[1]=path-suffix(/box.json) -> set-error(404) 31 | box_server_web_rules[2]=disallowed-methods(trace) 32 | ``` 33 | 34 | When you provide JSON, the `append` flag will be set to true when adding the configuration to what's already in CommandBox. 35 | 36 | Overridden env vars will not be written to the `server.json` file and will be lost when box stops. They will also take precedence and override any explicit `server.json` settings already set but will NOT override actual parameters to the `server start` command. 37 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/experimental-features.md: -------------------------------------------------------------------------------- 1 | # Experimental Features 2 | 3 | {% hint style="danger" %} 4 | Note, as of CommandBox 6, the old format of experimental Runwar args that look like `--name-here` is removed. There is a new syntax for specifying arbitrary experimental flags. 5 | {% endhint %} 6 | 7 | There are not any experimental features in CommandBox, but you can influence the JSON file used to configure runwar with the following syntax. 8 | 9 | ```bash 10 | server set runwar.options.path.to.option="value" 11 | ``` 12 | 13 | ```javascript 14 | { 15 | "runwar" : { 16 | "options" : { 17 | "path" : { 18 | "to" : { 19 | "option" : "value" 20 | } 21 | } 22 | } 23 | } 24 | } 25 | ``` 26 | 27 | The struct you specify will be merged into the JSON file that is sent to Runwar. Note, this JSON format is undocumented and subject to change. 28 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/gzip-compression.md: -------------------------------------------------------------------------------- 1 | # GZip Compression 2 | 3 | The web server in CommandBox is capable of enabling GZIp compression to reduce the size of HTTP responses. To enable GZip compress on your CommandBox server, add a `web.gzipEnable` setting in your `server.json` file. 4 | 5 | ```bash 6 | server set web.gzipEnable=true 7 | ``` 8 | 9 | By default GZip compression will be applied to any file over 1500 KB in size. This is because 1500 KB or smaller can fit inside a single network packet, so there's no real benifit in zipping small files and it just causes CPU overhead. 10 | 11 | If you wish to customize the file size or any other aspect of when GZip compression is applied, you can specify a custom [Undertow Predicate](server-rules/rule-language.md) that, when true, will trigger GZip for the request. 12 | 13 | ```bash 14 | server set web.gzipPredicate="request-larger-than(500)" 15 | ``` 16 | 17 | Since ANY valid Undertow predicate language can be used here you can combined predicates to control exactly when GZip compression is applied. This example would apply GZip compression to any CSS files over 500 KB that were not in the /admin folder. 18 | 19 | ```bash 20 | server set web.gzipPredicate="not path-prefix( admin ) and regex( '(.*).css' ) and request-larger-than(500)" 21 | ``` 22 | 23 | {% hint style="info" %} 24 | For [Multi-Site](../multi-site-support/), GZIP settings can be configured on a per-site basis in the `sites` object of the `server.json` or in a `.site.json` file. 25 | {% endhint %} 26 | 27 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/mime-types.md: -------------------------------------------------------------------------------- 1 | # MIME Types 2 | 3 | CommandBox will automatically set the content type in the HTTP response for common static file types. If you come across a file extention that doesn't have the correct type, you can set it like so in your `server.json`: 4 | 5 | ```bash 6 | server set web.mimeTypes.log=text/plain 7 | ``` 8 | 9 | Which creates the following 10 | 11 | ```json 12 | { 13 | "web":{ 14 | "mimeTypes":{ 15 | "log":"text/plain" 16 | } 17 | } 18 | } 19 | ``` 20 | 21 | In the above example, hitting a file such as `foo.log` would come back with a `text/plain` content type header. 22 | 23 | This setting will override any `` tag in your `web.xml` file. 24 | 25 | {% hint style="info" %} 26 | For [Multi-Site](../multi-site-support/), MIME Type settings can be configured on a per-site basis in the `sites` object of the `server.json` or in a `.site.json` file. 27 | {% endhint %} 28 | 29 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/performance-tuning.md: -------------------------------------------------------------------------------- 1 | # Performance Tuning 2 | 3 | Here are some settings for performance tuning your servers 4 | 5 | ## Max Requests 6 | 7 | This setting limits how many requests will be passed through the Undertow listener to your app server. It defaults to 8 times the number of CPU cores. Please note that your web server connector and Adobe ColdFusion or Lucee may also have their own max request settings. 8 | 9 | ```bash 10 | server set web.maxRequests=100 11 | ``` 12 | 13 | Or as a global setting for all servers: 14 | 15 | ```bash 16 | config set server.defaults.web.maxRequests=100 17 | ``` 18 | 19 | {% hint style="danger" %} 20 | Max Requests can NOT be set on a per-site basis since this setting controls the size of Undertow's worker task pool. You can, however, use the `request-limit( 10 )` handler in a server rule that applies only to a specific site. Keep in mind, the maxRequests setting will still enforce an overall total running threads for all sites on a server. 21 | {% endhint %} 22 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/proxy-ip.md: -------------------------------------------------------------------------------- 1 | # Proxy IP 2 | 3 | If CommandBox is running a server behind a trusted proxy which is known to set the `X-Forwarded-For` HTTP header, then you can enable this setting for the remote IP in your CF engine's `cgi` scope to represent the upstream IP. 4 | 5 | ``` 6 | server set web.useProxyForwardedIP=true 7 | ``` 8 | 9 | This is disabled by default. Otherwise a malicious client could send a fake `X-Forwarded-For` HTTP header to make it look like their traffic was coming from a trusted IP such as `127.0.0.1` to bypass any IP-based restrictions. Only enable this if you trust the proxy CommandBox is sitting behind. This should never be enabled if CommandBox is directly accessible on the internet. 10 | 11 | Enable for all servers like so: 12 | 13 | ``` 14 | config set server.defaults.web.useProxyForwardedIP=true 15 | ``` 16 | 17 | {% hint style="info" %} 18 | For [Multi-Site](../multi-site-support/), Proxy IP settings can be configured on a per-site basis in the `sites` object of the `server.json` or in a `.site.json` file. 19 | {% endhint %} 20 | 21 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/rest-servlet.md: -------------------------------------------------------------------------------- 1 | # REST Servlet 2 | 3 | The built in REST implementation in Adobe ColdFusion and Lucee is usually something you either love or hate. If you love it, you can enable it and customize the paths so it doesn't collide with your app's routes. if you hate it, you can turn it off. The REST servlet will be disabled unless you include a setting like so: 4 | 5 | ``` 6 | server set app.restMappings=/rest/*,/api/* 7 | ``` 8 | 9 | Note that the above setting will take over any URLs starting with `/rest` or `api` and you cannot use those routes or folders in your code. This is why it's handy to be able to modify or remove these. On a typical server, this is done via the `web.xml`, but CommandBox will do it all for you with just the setting above. 10 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/security/basic-authentication.md: -------------------------------------------------------------------------------- 1 | # Basic Authentication 2 | 3 | CommandBox's web server supports enabling Basic Auth on your sites. 4 | 5 | ``` 6 | server set web.security.basicAuth.enabled=true 7 | server set web.security.realm="My Realm" 8 | server set web.security.basicAuth.users.brad=pass 9 | server set web.security.basicAuth.users.luis=pass2 10 | ``` 11 | 12 | That will create the following data in your `server.json`, which will be picked up the next time you start your server. 13 | 14 | ```javascript 15 | { 16 | "web":{ 17 | "security" : { 18 | "realm" : "My Realm", 19 | "authPredicate" : "regex( pattern='^/lucee/admin/.*', case-sensitive=false )", 20 | "basicAuth":{ 21 | "users":{ 22 | "brad":"pass", 23 | "luis":"pass2" 24 | }, 25 | "enable":"true" 26 | } 27 | } 28 | } 29 | } 30 | ``` 31 | 32 | If there is no `authPredicate` set, basic auth with secure ALL PAGES on the site. Once you set an `authPredicate`, only the pages matching the predicate will require authentication. 33 | 34 | The old setting location for Basic Auth (`web.basicAuth`) will STILL WORK until the next major version of CommandBox, but should be considered deprecated. If both the settings exist (Ex: `web.basicAuth.enable` and `web.security.basicAuth.enable`), the new location will be given precedence. 35 | 36 | {% hint style="info" %} 37 | For [Multi-Site](../../multi-site-support/), any basic auth settings can be configured on a per-site basis in the `sites` object of the `server.json` or in a `.site.json` file. 38 | {% endhint %} 39 | 40 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/server-rules/allowed-static-files.md: -------------------------------------------------------------------------------- 1 | # Allowed Static Files 2 | 3 | The Undertow-based web server built into CommandBox will only serve up static files if they are in a list of valid extensions. This is to prevent prying eyes from hitting files they shouldn't be able to access on your server. 4 | 5 | The current list of valid extensions is: 6 | 7 | ``` 8 | 3gp,3gpp,7z,ai,aif,aiff,asf,asx,atom,au,avi,bin,bmp,btm,cco,crt,css,csv,deb,der,dmg, 9 | doc,docx,eot,eps,flv,font,gif,hqx,htc,htm,html,ico,img,ini,iso,jad,jng,jnlp,jpeg,jpg, 10 | js,json,kar,kml,kmz,m3u8,m4a,m4v,map,mid,midi,mml,mng,mov,mp3,mp4,mpeg,mpeg4,mpg,msi, 11 | msm,msp,ogg,otf,pdb,pdf,pem,pl,pm,png,ppt,pptx,prc,ps,psd,ra,rar,rpm,rss,rtf,run,sea, 12 | shtml,sit,svg,svgz,swf,tar,tcl,tif,tiff,tk,ts,ttf,txt,wav,wbmp,webm,webp,wmf,wml,wmlc, 13 | wmv,woff,woff2,xhtml,xls,xlsx,xml,xpi,xspf,zip,aifc,aac,apk,bak,bk,bz2,cdr,cmx,dat, 14 | dtd,eml,fla,gz,gzip,ipa,ia,indd,hey,lz,maf,markdown,md,mkv,mp1,mp2,mpe,odt,ott,odg, 15 | odf,ots,pps,pot,pmd,pub,raw,sdd,tsv,xcf,yml,yaml 16 | ``` 17 | 18 | If you have a common static file you need to serve, you can add your own custom extensions to the list like so: 19 | 20 | ```bash 21 | server set web.allowedExt=jar,exe,dll 22 | ``` 23 | 24 | {% hint style="info" %} 25 | For [Multi-Site](../../multi-site-support/), allowed static files settings can be configured on a per-site basis in the `sites` object of the `server.json` or in a `.site.json` file. 26 | {% endhint %} 27 | 28 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/server-rules/custom-predicates-handlers.md: -------------------------------------------------------------------------------- 1 | # Custom Predicates/Handlers 2 | 3 | CommandBox bundles some custom predicates and handlers to make your life easier. 4 | 5 | The predicate `cf-admin()` will returns `true` if the incoming URL is to the Lucee or ColdFusion admin: 6 | 7 | ```javascript 8 | cf-admin() -> set-error( 404 ); 9 | 10 | // Is the equivalent of 11 | regex(pattern='^/(CFIDE/administrator|CFIDE/adminapi|CFIDE/AIR|CFIDE/appdeployment|CFIDE/cfclient|CFIDE/classes|CFIDE/componentutils|CFIDE/debug|CFIDE/images|CFIDE/orm|CFIDE/portlets|CFIDE/scheduler|CFIDE/ServerManager|CFIDE/services|CFIDE/websocket|CFIDE/wizards|lucee/admin)/.*', case-sensitive=false) -> set-error(404) 12 | 13 | ``` 14 | 15 | The handler `block-external()` blocks any request not from localhost with a 404 response code. You can pair this with any predicate you choose. 16 | 17 | ```javascript 18 | cf-admin() -> block-external() 19 | 20 | // Is the equivalent of 21 | cf-admin() -> ip-access-control( default-allow=false, failure-status=404, acl={ 127.*.*.* allow } ) 22 | ``` 23 | 24 | The handler `block-cf-admin()` blocks any request to the Lucee or ColdFusion admin with a 404 response code. 25 | 26 | ```javascript 27 | block-cf-admin() 28 | 29 | // Is the equivalent of 30 | cf-admin() -> set-error( 404 ); 31 | ``` 32 | 33 | ## Build Your Own 34 | 35 | You can build your own predicates and handlers by compiling java classes that implement the `io.undertow.predicate.PredicateBuilder` or `io.undertow.server.handlers.builder.HandlerBuilder` interfaces. If the proper service metadata is present in your jar's META-INF folder, undertow will automatically find and register your builders via Java's service loader. 36 | 37 | This isn't super difficult but involves a few moving parts. If you're interested in writing your own handlers and predicates to use in your server rules, reach out on the mailing list and we'll walk you through it. 38 | 39 | You can see the custom handlers and predicates documented above in our Runwar source code here: 40 | 41 | **Custom handlers:** 42 | 43 | {% @github-files/github-code-block %} 44 | 45 | **Custom Predicates:** 46 | 47 | {% @github-files/github-code-block %} 48 | 49 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/server-rules/debugging-server-rules.md: -------------------------------------------------------------------------------- 1 | # Debugging Server Rules 2 | 3 | And to test/debug your rules, start your server with the trace flag and tail the console output. Every hit in your browser will output several lines of debugging for each rule that is processed. 4 | 5 | ```bash 6 | server start --trace --console 7 | ``` 8 | 9 | With the custom rule above, you'd see something like this: 10 | 11 | ``` 12 | [DEBUG] requested: '/CFIDE/main/ide.cfm' 13 | [TRACE] io.undertow.predicate: Path(s) [/CFIDE/main/ide.cfm] MATCH input [/CFIDE/main/ide.cfm] for HttpServerExchange{ GET /CFIDE/main/ide.cfm}. 14 | [TRACE] io.undertow.predicate: Predicate [path( '/CFIDE/main/ide.cfm' )] resolved to true. Next handler is [done] for HttpServerExchange{ GET /CFIDE/main/ide.cfm}. 15 | [TRACE] io.undertow.predicate: Predicate chain marked done. Next handler is [Runwar PathHandler] for HttpServerExchange{ GET /CFIDE/main/ide.cfm}. 16 | [WARN ] responded: Status Code 200 (/CFIDE/main/ide.cfm) 17 | ``` 18 | -------------------------------------------------------------------------------- /embedded-server/configuring-your-server/undertow-options.md: -------------------------------------------------------------------------------- 1 | # Undertow Options 2 | 3 | CommandBox uses JBoss Undertow to power it's lightweight servlet containers. Undertow also powers JBoss Wildfly and has a lot of configurable options, not all of which have first-class CommandBox settings. These low-level settings come in two different categories: 4 | 5 | * **Undertow Options** - Settings that apply to the servlet and web server aspects of Undertow 6 | * **XNIO Options** - Part of the underlying XNIO library which powers all low-level I/O in undertow 7 | 8 | ## Undertow Options 9 | 10 | Undertow has its own set of options which can be found here: 11 | 12 | {% embed url="http://undertow.io/javadoc/2.0.x/io/undertow/UndertowOptions.html" %} 13 | 14 | To set an XNIO option that CommandBox doesn't already expose with a first-class setting, you can set them into your `server.json` like so: 15 | 16 | ```bash 17 | server set runwar.undertowOptions.ALLOW_UNESCAPED_CHARACTERS_IN_URL=true 18 | ``` 19 | 20 | You can also set global XNIO objects that will apply to all servers. Global options will be appended to server-level options. 21 | 22 | ```bash 23 | config set server.defaults.runwar.undertowOptions.WORKER_NAME=myWorker 24 | ``` 25 | 26 | ## XNIO Options 27 | 28 | XNIO (which is a refined version of NIO (Non-blocking I/O) has its own set of options that apply to the low level network transport functions it provides. You can find the full set of XNIO options here: 29 | 30 | {% embed url="https://javadoc.io/doc/org.jboss.xnio/xnio-api/latest/org/xnio/Options.html" %} 31 | 32 | To set an XNIO option that CommandBox doesn't already expose with a first-class setting, you can set them into your `server.json` like so: 33 | 34 | ```bash 35 | server set runwar.XNIOOptions.WORKER_NAME=myWorker 36 | server set runwar.XNIOOptions.SSL_ENABLED_PROTOCOLS=TLSv1.3,TLSv1.2 37 | ``` 38 | 39 | You can also set global XNIO objects that will apply to all servers. Global options will be appended to server-level options. 40 | 41 | ```bash 42 | config set server.defaults.runwar.XNIOOptions.WORKER_NAME=myWorker 43 | config set server.defaults.runwar.XNIOOptions.SSL_ENABLED_PROTOCOLS=TLSv1.3,TLSv1.2 44 | ``` 45 | -------------------------------------------------------------------------------- /embedded-server/debugging-server-starts.md: -------------------------------------------------------------------------------- 1 | # Debugging Server Starts 2 | 3 | If a server isn't starting, the first thing to run is the `server log` command. It will show you the console log for that server. Note, this dumps the entire log file to the console, which may be very large. We recommend using the `tail` or `--follow` tricks below. 4 | 5 | ``` 6 | server log 7 | server log serverName 8 | ``` 9 | 10 | ## Tailing and Following logs 11 | 12 | If the log is very large, use the `tail` command to just see the last few lines of it. 13 | 14 | ``` 15 | server log | tail 16 | server log | tail lines=100 17 | ``` 18 | 19 | To get a live stream of the console log from a running server, use the `--follow` flag and the command will continue streaming new lines to the console until you press Ctrl-C to stop. 20 | 21 | ``` 22 | server log --follow 23 | ``` 24 | 25 | You can also look at your server's access log (if enabled) and rewrite log (if enabled). 26 | 27 | ``` 28 | server log --follow -access 29 | server log --follow --rewrite 30 | ``` 31 | 32 | ## Start server in console mode 33 | 34 | You can use the `--console` flag to the `server start` command to start a server in the foreground. The console log will be live-streamed to the CLI and the log will continue streaming as long as the server is running. Press Ctrl-C to stop the server and stop streaming the log file. 35 | 36 | ``` 37 | server start --console 38 | ``` 39 | 40 | ## Debug Logging 41 | 42 | You can get additional information about a server start with the `--debug` flag. When debug is set, the `start` command will not exit immediately, but wait for the server to come up and live stream the debugging information and server logs to the console while the server is coming up. 43 | 44 | ``` 45 | server start --debug 46 | server start --debug --console 47 | ``` 48 | 49 | ## Maximum logging! (trace) 50 | 51 | You may still really be having issues getting your server to start up correctly due to a setting not getting picked up, rewrites not working, or maybe a jar not loading. You can "drink from the firehose" so to speak by turning on `trace` level logging. This works best when starting the server via the console so you can watch the logging as it streams past. 52 | 53 | ``` 54 | server start --trace --console 55 | ``` 56 | -------------------------------------------------------------------------------- /embedded-server/install-lucee-core-lex-files.md: -------------------------------------------------------------------------------- 1 | # Install Lucee core/lex files 2 | 3 | The `install` command will automatically find a local Lucee Server when installing a package that is a Lex file. There is also now a command called `server lucee-deploy` to help with installing Lex files (Lucee Extensions) and LCO files (Lucee Core). 4 | 5 | It will accept an absolute or relative local file path: 6 | 7 | ```bash 8 | server lucee-deploy myFile.lex 9 | ``` 10 | 11 | or an HTTP URL to download 12 | 13 | ```bash 14 | server lucee-deploy https://domain.com/path/to/Lucee-core-patch.lco 15 | ``` 16 | 17 | You can also override the name of the CommandBox server to install into, regardless of what working directory the shell is in: 18 | 19 | ```bash 20 | server lucee-deploy myFile.lex myServer 21 | ``` 22 | 23 | The command will copy the lex or lco file to the deploy folder of the chosen Lucee server following these rules 24 | 25 | * If server name is passed as second arg, use that server name (providing it’s a Lucee server) 26 | * Otherwise, if this command is being run inside of a server-related interceptor, capture the name of the server from the intercept data and use that server 27 | * otherwise, look for any Lucee server whose webroot points to the current working directory of the shell and use the first found 28 | * Otherwise, look for a `LUCEE_DEPLOY_DIRECTORY` env var and use this as the deploy directory (can be relative or absolute) 29 | 30 | -------------------------------------------------------------------------------- /embedded-server/offline-server-starts.md: -------------------------------------------------------------------------------- 1 | # Offline Server Starts 2 | 3 | Sometimes you may wish to start a server on a computer that doesn't have access to the Internet. However, you may notice that running a command such as the following will throw an error trying to connect to ForgeBox: 4 | 5 | ```bash 6 | start cfengine=lucee@5.x 7 | ``` 8 | 9 | That is because `5.x` is a semver range and not a specific version. CommandBox must connect to ForgeBox to see what versions of the CF engine `lucee` can be found to use the latest one. 10 | 11 | ## Be More Specific 12 | 13 | If you know that a CF engine is already downloaded in your server's artifacts directory, start your server with a specific major, minor, patch, and build version to skip the ForgeBox check. 14 | 15 | ```bash 16 | start cfengine=lucee@5.0.0+252 17 | ``` 18 | 19 | NOTE: If this fails, check the location of the folder structure below the artifacts folder for it's exact path.\ 20 | e.g. /artifacts/lucee/5.0.0+252/lucee.zip - The box command for this would be: start cfengine=lucee@5.0.0+252\ 21 | This follows the pattern:\ 22 | /artifacts/\[server-type]/\[server-version]/\[server-type].zip\ 23 | Useful if you've manually downloaded the file from forgebox and need to rename it. 24 | 25 | ## Fail Safe 26 | 27 | If CommandBox needs to connect to ForgeBox to resolve a version number and ForgeBox is unavailable, it will look in your local artifacts cache to try and find a cached version of that CF engine that satisfies your semver range. This means you may not get the latest version of that CF Engine, but at least your server will start up. 28 | -------------------------------------------------------------------------------- /embedded-server/server-processes.md: -------------------------------------------------------------------------------- 1 | # Server Processes 2 | 3 | It's important to note that each server you start opens a new Java process on your host operating system. This allows each server to have it's own settings and configuration independent of any other server. Start as many as you need and simply stop them when you're done. Just keep in mind each server gets its own heap space so keep an eye on your available RAM. 4 | 5 | ## Server Runs Independant of CLI 6 | 7 | The embedded server instances are also a separate process from the actual CommandBox CLI process, which also runs on Java. This means you can open the interactive shell, start a few servers, then quit the shell, yet the servers will still continue to run. You can use the CLI to issue a `stop` command in the servers web root, or just right click on the tray icon. 8 | 9 | There is currently no way to have servers start automatically when your computer boots, though there's nothing preventing you from setting up a local script to run the start commands for you. 10 | 11 | ## WEB-INF 12 | 13 | You may be used to having your server's WEB-INF folder living in your web root. The CommandBox embedded server still has a dedicated WEB-INF folder for each server you start, but it lives under the main CommandBox installation directory in your user folder. Changes you make to the WEB-INF such as adding jars or new tags will be persisted until you issue a `server forget` command. 14 | -------------------------------------------------------------------------------- /embedded-server/server-scripts.md: -------------------------------------------------------------------------------- 1 | # Server Scripts 2 | 3 | Server scripts work just like [Package Scripts](../package-management/package-scripts.md), but they only apply to server-related interceptor points, and they go in your `server.json`. If you have several servers in a folder with their own `server-name.json` files, the server scripts can be different per server. 4 | 5 | The interception points which will fire a server script are: 6 | 7 | * `preServerStart` 8 | * `onServerStart` 9 | * `onServerInstall` 10 | * `onServerInitialInstall` 11 | * `onServerStop` 12 | * `preServerForget` 13 | * `postServerForget` 14 | 15 | Read more about when these interception points fire [here](../developing-for-commandbox/interceptors/core-interception-points/). 16 | 17 | Configure server scripts like so in your `server.json`: 18 | 19 | ```json 20 | { 21 | "scripts":{ 22 | "onServerInstall":"cfpm list" 23 | } 24 | } 25 | ``` 26 | 27 | ### Ad-hoc server scripts 28 | 29 | Just like package scripts, you can also create ad-hoc scripts for a given server. They are executed with the `server run-script` command. Define them as additional keys in the `scripts` block. 30 | 31 | ```json 32 | { 33 | "name" : "My Server" 34 | "scripts":{ 35 | "myScript":"server log --follow" 36 | } 37 | } 38 | ``` 39 | 40 | And run them like so: 41 | 42 | ``` 43 | server run-script myScript 44 | ``` 45 | 46 | ### Running multiple commands 47 | 48 | You can run several commands into a single one using `&&`. You can also do this by specifying an array of strings instead of a string like so: 49 | 50 | ```json 51 | { 52 | "name" : "My Server", 53 | "scripts" : { 54 | "updateCode" : [ 55 | "server stop", 56 | "!git pull", 57 | "server start" 58 | ], 59 | } 60 | } 61 | ``` 62 | 63 | This can be much more readable for multiple commands. Note, this is functionality equivalent to using `&&`, which means any erroring command will stop execution. 64 | 65 | -------------------------------------------------------------------------------- /embedded-server/server.json/packaging-your-server.md: -------------------------------------------------------------------------------- 1 | # Packaging Your Server 2 | 3 | `server.json` allows you to package up an app that requires special start settings such as rewrites, JVM args, or heap size, and anyone can run it with the same settings you do by simply typing `server start`. Make sure to not deploy the `server.json` file to your production server where it may be web-accessible. 4 | 5 | ### Storing `server.json` outside the web root 6 | 7 | To help with this, you can store your `server.json` file outside of the web root and use the `web.webroot` property in it to point to the location of the web root. This can be an absolute path or a relative path to the location of the JSON file. 8 | 9 | ```bash 10 | server set web.webroot=www 11 | ``` 12 | 13 | When you start the server, you can run the `start` command from the same directory that the `server.json` file lives, or specifiy the path to the JSON file like so: 14 | 15 | ```bash 16 | start /path/to/server.json 17 | ``` 18 | 19 | ## Determining the web root 20 | 21 | If there is no web root in your `server.json`, CommandBox will use the folder that the JSON file is stored in. If there is no JSON file at all, the current working directory is used. 22 | -------------------------------------------------------------------------------- /embedded-server/server.json/working-with-server.json.md: -------------------------------------------------------------------------------- 1 | # Working with server.json 2 | 3 | Interacting with the `server.json` file uses the commands `server set`, `server show`, and `server clear`, which work the same as the `package set/show/clear` commands. 4 | 5 | Set the port for your server: 6 | 7 | ```bash 8 | server set web.http.port=8080 9 | ``` 10 | 11 | View the port: 12 | 13 | ```bash 14 | server show web.http.port 15 | ``` 16 | 17 | View the port with JMESPath: 18 | 19 | ```bash 20 | server show jq:web.http.port 21 | ``` 22 | 23 | Remove the saved setting: 24 | 25 | ```bash 26 | server clear web.http.port 27 | ``` 28 | -------------------------------------------------------------------------------- /embedded-server/single-server-mode.md: -------------------------------------------------------------------------------- 1 | # Single Server Mode 2 | 3 | CommandBox is designed to allow you to start, stop, and manage as many servers as you like. However, when using CommandBox in an environment such as Docker containers where you only ever want to have a single server, this can cause issues where warming up the server with different names creates more than one server. You can enable **Single Server Mode** which will only allow CommandBox to have a single server that shows when you run the `server list` command. 4 | 5 | ```bash 6 | config set server.singleServerMode=true 7 | ``` 8 | 9 | This is a global setting that takes immediate effect. If you already have more than one server defined, it will not remove the extra ones, it will simply re-use the first server it finds. In this mode, the server name becomes essentially meaningless. Each of these commands would use the same default server 10 | 11 | ```bash 12 | start name=foo 13 | stop name=bar 14 | restart name=brad 15 | ``` 16 | 17 | -------------------------------------------------------------------------------- /embedded-server/start-html-server.md: -------------------------------------------------------------------------------- 1 | # Start HTML Server 2 | 3 | You may want to start up a local server that does not have a CF Engine such as Lucee or Adobe ColdFusion installed. You can do this as of CommandBox 5.1.0 by setting the `cfengine` parameter to `none` like so: 4 | 5 | ``` 6 | server start cfengine=none 7 | ``` 8 | 9 | Or in your `server.json` like this 10 | 11 | ``` 12 | server set app.cfengine=none 13 | server start 14 | ``` 15 | 16 | This server will support everything that you are used to including the `server.json` file, heap settings, ports, and virtual directories. The only difference is it will server everything as static files. (.cfm or .cfc files will not be processed) 17 | -------------------------------------------------------------------------------- /embedded-server/starting-as-a-service.md: -------------------------------------------------------------------------------- 1 | # Starting as a Service 2 | 3 | When using CommandBox on a staging or production server, you may wish to start up servers as a service when the OS comes online. The recommended approach is to use the [**CommandBox Service Manager Module**](https://www.ortussolutions.com/products/commandbox-service-manager), which is a commercial module that handles all major operating systems (Linux, Mac, Windows) automatically. 4 | 5 | ![CommandBox Service Manager](<../.gitbook/assets/image (9) (1).png>) 6 | 7 | See screencast here: 8 | 9 | {% embed url="https://www.ortussolutions.com/products/commandbox-service-manager" %} 10 | 11 | Alternatively, you can manually do so following one of these community guides. 12 | 13 | ## Windows 14 | 15 | See screencast here: [https://www.ortussolutions.com/blog/screencast-starting-commandbox-servers-as-a-windows-service](https://www.ortussolutions.com/blog/screencast-starting-commandbox-servers-as-a-windows-service) 16 | 17 | ## MacOS 18 | 19 | Coming soon... 20 | 21 | ## CentOS/RHEL/Ubuntu (system.d) 22 | 23 | Create a `.service` file 24 | 25 | ``` 26 | nano /usr/lib/systemd/system/mySite.service 27 | ``` 28 | 29 | as follows: 30 | 31 | ``` 32 | [Unit] 33 | Description=mySite Service 34 | 35 | [Service] 36 | ExecStart=/usr/local/bin/box server start /var/www/mySiteAPI/server.json 37 | Type=forking 38 | 39 | [Install] 40 | WantedBy=multi-user.target 41 | ``` 42 | 43 | Start the service 44 | 45 | ``` 46 | systemctl start mySite.service 47 | ``` 48 | 49 | Give the service about a minute to load up, then check its status 50 | 51 | ``` 52 | systemctl status mySite.service 53 | ``` 54 | 55 | Once you've verified the service is running as expected, enable the service to load at boot 56 | 57 | ``` 58 | systemctl enable mySite.service 59 | ``` 60 | -------------------------------------------------------------------------------- /forgebox-enterprise/commands/README.md: -------------------------------------------------------------------------------- 1 | # Commands 2 | 3 | Integrating CommandBox with your own ForgeBox endpoint is very simple. Please review the available commands and follow our guide to learn how to interact with ForgeBox from the CLI. 4 | 5 | This is a list of the commands you have available to integrate with ForgeBox enterprise. 6 | 7 | * `forgebox endpoint list` 8 | * `forgebox endpoint register` 9 | * `forgebox endpoint remove` 10 | * `forgebox endpoint set-default` 11 | 12 | {% hint style="info" %} 13 | You can always ask CommandBox for help by adding a question mark at the end of your command.\ 14 | e_xample: `forgebox endpoint ?`_ 15 | {% endhint %} 16 | -------------------------------------------------------------------------------- /forgebox-enterprise/commands/list.md: -------------------------------------------------------------------------------- 1 | # List 2 | 3 | _https://www.forgebox.io/api/v1/_ is the default endpoint and you can always check your registered endpoints by typing\ 4 | `forgebox endpoint list` 5 | 6 | ![](<../../.gitbook/assets/forgebox-endpoint-default-list (1) (1).gif>) 7 | -------------------------------------------------------------------------------- /forgebox-enterprise/commands/login.md: -------------------------------------------------------------------------------- 1 | # Login 2 | 3 | The next step is to authenticate against your endpoint using valid credentials as is shown below:\ 4 | `forgebox login endpointName=stg-forgebox` 5 | 6 | ![](../../.gitbook/assets/forgebox-endpoint-login.gif) 7 | 8 | {% hint style="info" %} 9 | Enter your username and password and make sure you authenticate successfully. 10 | {% endhint %} 11 | -------------------------------------------------------------------------------- /forgebox-enterprise/commands/register.md: -------------------------------------------------------------------------------- 1 | # Register 2 | 3 | In order to register a new endpoint, just give it a name and set your endpoint as follows:\ 4 | `forgebox endpoint register stg-forgebox https://forgebox.stg.ortushq.com/api/v1/` 5 | 6 | ![](<../../.gitbook/assets/forgebox-endpoint-register (1).gif>) 7 | -------------------------------------------------------------------------------- /forgebox-enterprise/commands/remove.md: -------------------------------------------------------------------------------- 1 | # Remove 2 | 3 | You can remove endpoints anytime by using the remove command:\ 4 | `forgebox endpoint remove demo-endpoint` 5 | 6 | ![](../../.gitbook/assets/forgebox-endpoint-remove.gif) 7 | -------------------------------------------------------------------------------- /forgebox-enterprise/commands/set-default.md: -------------------------------------------------------------------------------- 1 | # Set Default 2 | 3 | If you want to update your endpoint to be the default one, just do it like this:\ 4 | `forgebox endpoint set-default stg-forgebox` 5 | 6 | ![](../../.gitbook/assets/forgebox-endpoint-set-default.gif) 7 | 8 | This will default your endpoint and you will be able to install packages from your endpoint without giving a namespace. 9 | 10 | {% hint style="info" %} 11 | You can verify that your default endpoint has changed by executing the list command. 12 | {% endhint %} 13 | -------------------------------------------------------------------------------- /forgebox-enterprise/introduction.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | ForgeBox Enterprise is an offering by Ortus Solutions that allows you to have a custom and private hosted version of ForgeBox for your company to use. You can always use the public ForgeBox version if you want too. 4 | 5 | All the goodness of the community version, but with the **exclusivity** and **security** of your own instance to collaborate, modernize and conquer! 6 | 7 | ### Capabilities 8 | 9 | FORGEBOX ENTERPRISE is a hosted **private** software registry with exclusive security, collaboration and scalability features. Empower your development teams to build applications rapidly, modern and secure. FORGEBOX ENTERPRISE will enhance development team the following capabilities: 10 | 11 | * Private software registry to manage and shared code packages (engines, projects, demos, modules, etc. ) across your organization. 12 | * Public or Private packages 13 | * Internal collaborators and access controls 14 | * Custom named integration with CommandBox CLI. 15 | * Fine grained User Access Control, Roles and Permissions. 16 | * Package type management 17 | * Scalable Artifact Storage 18 | * Up to 250GB of storage included 19 | * SSL Included 20 | * Software firewall included 21 | * Artifact CDN Included 22 | * Enterprise Support, SLAs and mentorship 23 | * Containerized Environment with redundancy and scalability 24 | * Package Security Audits (\*\*Coming Soon) 25 | * Package white and black lists (\*\*Coming Soon) 26 | * Two-factor authentication (\*\*Coming Soon) 27 | * Single Sign On (\*\*Coming Soon) 28 | 29 | {% hint style="info" %} 30 | Please note that you will need [CommandBox 4.5](https://www.ortussolutions.com/products/commandbox) or later to integrate ForgeBox with your own endpoint. 31 | {% endhint %} 32 | 33 | -------------------------------------------------------------------------------- /forgebox-enterprise/storage.md: -------------------------------------------------------------------------------- 1 | # Storage 2 | 3 | Every FORGEBOX Enterprise includes up to 250GB of binary storage with elastic capabilities. 4 | 5 | ## Storing Package Binaries on ForgeBox 6 | 7 | ForgeBox can store the binaries for your packages in the ForgeBox Cloud. This provides you with an easy way to store multiple versions of your package distributed across the globe. 8 | 9 | To utilize ForgeBox Storage, simply set `forgeboxStorage` as the value of your package's `location`. 10 | 11 | ```bash 12 | CommandBox:my-package> package set location=forgeboxStorage 13 | ``` 14 | 15 | When you publish a package, CommandBox will automatically zip up your package and send it to ForgeBox. 16 | -------------------------------------------------------------------------------- /forgebox-enterprise/usage.md: -------------------------------------------------------------------------------- 1 | # Usage 2 | 3 | Once you have registered your endpoint and you are authenticated, you are able to install packages from your own endpoint like this:\ 4 | `install stg-forgebox:coldbox` 5 | 6 | ![](<../.gitbook/assets/forgebox-endpoint-default-list (1).gif>) 7 | 8 | In the previous example you can see we are installing a `coldbox` package from `stg-forgebox` which is our own endpoint instead of the default one. 9 | 10 | {% hint style="info" %} 11 | You can set your own endpoint as default and then you will not need to use the namespace to refer to your endpoint. In the following example, we will ask CommandBox to retrieve a `coldbox` package from our own endpoint without using a namespace 12 | 13 | example: `install coldbox` 14 | {% endhint %} 15 | -------------------------------------------------------------------------------- /helpful-commands/README.md: -------------------------------------------------------------------------------- 1 | # Helpful Commands 2 | 3 | Here are some helpful commands that can come in handy when writing task runners for automating builds via CFML. Of course, since these are just commands, they can be run directly from the CLI as well by you. 4 | -------------------------------------------------------------------------------- /helpful-commands/ask-and-confirm.md: -------------------------------------------------------------------------------- 1 | # ask and confirm 2 | 3 | Here are some fun commands for user interactivity in the shell. You can use these as part of a recipe or a nice "one-liner". 4 | 5 | ### ask 6 | 7 | The `ask` command is similar to the `ask()` method in Task Runners. It requires an interactive terminal and will ask the user a question and return their answer. It is meant to be changed with other commands. 8 | 9 | ```bash 10 | set color=`ask "favorite Color? "` 11 | echo "you said ${color}" 12 | ``` 13 | 14 | or with default values 15 | 16 | ```bash 17 | ask question="Who is cool? " defaultResponse="Balbino!" 18 | ``` 19 | 20 | or with masked input 21 | 22 | ```bash 23 | ask question="What is your password? " mask=* 24 | ``` 25 | 26 | Or fun stuff like this 27 | 28 | ```bash 29 | ask "Secret phrase: " | assertEqual "mockingbird" || echo "access denied!" && exit 1 30 | ``` 31 | 32 | ### confirm 33 | 34 | The `confirm` command will ask the user a yes/no question and return a passing or failing exit code from the command based on the answer. 35 | 36 | ```bash 37 | confirm "do you want to update your packages? " && update 38 | ``` 39 | 40 | Remember the `&&` operator will only execute the second command if the first command returns an exit code of `0`. 41 | -------------------------------------------------------------------------------- /helpful-commands/checksums.md: -------------------------------------------------------------------------------- 1 | # Checksums 2 | 3 | Another very common requirement for builds is generating checksums on your files. We've got you covered here now as well. Run `checksum help` for even more options. 4 | 5 | ## From the CLI 6 | 7 | ``` 8 | checksum file.txt 9 | checksum path=build.zip algorithm=SHA-256 10 | ``` 11 | 12 | ## From CFML 13 | 14 | ```javascript 15 | command( 'checksum' ) 16 | .params( 'file.txt' ) 17 | .run(); 18 | 19 | command( 'checksum' ) 20 | .params( path = 'build.zip', algorithm = 'SHA-256' ) 21 | .run(); 22 | ``` 23 | 24 | ## Checksum all files in a directory 25 | 26 | You can provide a file globbing pattern to receive a checksum for all files in a directory that match that pattern. 27 | 28 | ``` 29 | checksum *.cfc 30 | ``` 31 | 32 | ## Output format 33 | 34 | The `checksum` command also supports some other popular formats for outputting checksums. The default format is `checksum`. 35 | 36 | ``` 37 | checksum path=**.cfc format=checksum 38 | checksum path=**.cfc format=sfv 39 | checksum path=**.cfc format=md5sum 40 | ``` 41 | 42 | ## Write out checksums 43 | 44 | The `checksum` command will also write out a file that contains the hash which is a common requirement for builds that produce artifacts. 45 | 46 | Write checksum(s) to a file named after the original file plus a new extension. This will create a file called `myFile.zip.md5`. 47 | 48 | ``` 49 | checksum myFile.zip md5 --write 50 | ``` 51 | 52 | Control the file extension like so. (`--write` is optional when supplying an extension) This will create a file called `myFile.zip.hash`. 53 | 54 | ``` 55 | checksum path=myFile.zip extension=hash --write 56 | ``` 57 | 58 | ## Verify a file against an existing checksum 59 | 60 | You can check a file against an existing checksum to make sure the file hasn't changed. 61 | 62 | ``` 63 | checksum path=myFile.zip verify=2A95F32028087699CCBEB09AFDA0348C 64 | ``` 65 | -------------------------------------------------------------------------------- /helpful-commands/code-quality-tools.md: -------------------------------------------------------------------------------- 1 | # Code Quality Tools 2 | 3 | Here's some commands to help with code quality. You can use them as a one-time clean up and then use them as part of your regular build to maintain your coding rules. 4 | 5 | ## Normalize Indents (Tabs vs Spaces) 6 | 7 | Ahh, the age-old debate of tabs vs spaces. Make sure you have a solid discussion with your team and decide which one is correct (tabs, obviously!) and then use this command to implement it across your entire code base. 8 | 9 | ### From the CLI 10 | 11 | ``` 12 | utils normalize-indents **.cf? 13 | ``` 14 | 15 | ### From CFML 16 | 17 | ``` 18 | command( 'indents' ) 19 | .params( '**.cf*' ) 20 | .run(); 21 | ``` 22 | 23 | ## Remove Trailing Spaces 24 | 25 | Removes trailing whitespace from the ends of your lines. 26 | 27 | ### From the CLI 28 | 29 | ``` 30 | utils remove-trailing-spaces **.cf* 31 | ``` 32 | 33 | ### From CFML 34 | 35 | ```javascript 36 | command( 'rts' ) 37 | .params( '**.cf*' ) 38 | .run(); 39 | ``` 40 | 41 | ## Add final EOL character 42 | 43 | Makes sure the last line of every source file has an EOL character. 44 | 45 | ### From the CLI 46 | 47 | ``` 48 | utils add-eol-at-eof **.cf* 49 | ``` 50 | 51 | ### From CFML 52 | 53 | ```javascript 54 | command( 'eol' ) 55 | .params( '**.cf*' ) 56 | .run(); 57 | ``` 58 | -------------------------------------------------------------------------------- /helpful-commands/token-replacements.md: -------------------------------------------------------------------------------- 1 | # Token Replacements 2 | 3 | One common thing in builds is replacing a token placeholder across all files, or perhaps certain files defined by a file globbing pattern. We've got a special command for that. 4 | 5 | ## From the CLI 6 | 7 | ``` 8 | tokenReplace path=/tests/*.cfc token="@@version@@" replacement=`package version` 9 | ``` 10 | 11 | ## From CFML 12 | 13 | ```javascript 14 | command( 'tokenReplace' ) 15 | .params( 16 | path = "/tests/*.cfc", 17 | token = "@@version@@", 18 | replacement = command( 'package version' ).run() 19 | ) 20 | .run(); 21 | ``` 22 | -------------------------------------------------------------------------------- /ide-integrations/README.md: -------------------------------------------------------------------------------- 1 | # IDE Integrations 2 | 3 | Even though you can run CommandBox from your favorite terminal window, there are a number of nice IDE integrations out there that are designed to allow you to run command line utilities from inside your favorite editor. Here's a few that we're aware of and how to use them. If you have more, please let us know! 4 | -------------------------------------------------------------------------------- /overview.md: -------------------------------------------------------------------------------- 1 | # Overview 2 | 3 | ![CommandBox CLI](<.gitbook/assets/image (16).png>) 4 | 5 | CommandBox is a standalone, native Command Line Interface (**CLI**), Package Manager, Embedded CFML Server and Read Eval Print Loop (**REPL**) aimed to help ColdFusion (CFML) developers become more productive through automation, dependency management, command line-based tools, and ASCII snake games. 6 | 7 | ## Features at a Glance 8 | 9 | CommandBox is an amalgamation of many different tools and borrows concepts from NPM, Grunt/Gulp, Maven, Bower, and Node. Features include: 10 | 11 | * Command Line for ColdFusion (CFML) 12 | * Operating System integration for executing commands 13 | * Ability to create and execute commands built using ColdFusion (CFML) 14 | * ForgeBox integration for cloud package management and installations 15 | * ColdBox Platform, TestBox, and ContentBox CMS Integrations 16 | * Integrated servlet server with rewrite capabilities 17 | * Ability to create command recipes and execution 18 | * REPL (Read-Evaluate-Print-Loop) console for immediate ColdFusion 19 | 20 | (CFML) interaction 21 | * Ability to interact with user via CLI and create workflows and 22 | 23 | installers 24 | * Ability to execute workflows and tasks 25 | * Built-in Help system 26 | -------------------------------------------------------------------------------- /package-management/README.md: -------------------------------------------------------------------------------- 1 | # Package Management 2 | 3 | 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. 4 | 5 | ``` 6 | install myPackage 7 | ``` 8 | 9 | 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. 10 | 11 | You can easily create your own packages and register them on ForgeBox so the whole community can start using them. 12 | -------------------------------------------------------------------------------- /package-management/artifacts.md: -------------------------------------------------------------------------------- 1 | # Artifacts 2 | 3 | CommandBox automatically keeps a local copy of every package it downloads called an artifact. These are stored in the `~/.CommandBox/artifacts/` folder. The next time you install the same package, the file in your local artifacts cache will be used to prevent another download. 4 | 5 | When installing a package, CommandBox will check its local artifacts first and use the zip file found there first. If nothing is found, the package will be downloaded from the ForgeBox download URL and then cached in the artifacts directory for next time. 6 | 7 | Artifacts are organized by folders named after the package slug, and then folders inside named after the version. You can get a list of all your artifacts with the `artifacts list` command. 8 | 9 | ```bash 10 | CommandBox> artifacts list 11 | Found 5 artifact(s) (/.CommandBox/artifacts) 12 | cbcompat - 1 version(s) 13 | *1.0.1.0 14 | cbstorages - 1 version(s) 15 | *1.0.0 16 | coldbox-be - 1 version(s) 17 | *4.0.0 18 | cbjavaloader - 1 version(s) 19 | *1.0.0 20 | cbfeeds - 1 version(s) 21 | *1.0.0 22 | ``` 23 | 24 | You can clear individual artifacts by slug and version with the `artifacts remove` command. Or just wipe all of them with `artifacts clean`. 25 | 26 | > **info** The artifact cache is only used by the ForgeBox endpoint. It is the only remote endpoint capable of telling CommandBox what the latest version of a package is without downloading it again. 27 | 28 | ## Snapshot versions 29 | 30 | CommandBox will cache snapshot package versions in the artifacts cache, but it will still download them every time. A snapshot version is one that has a preReleaseID of `snapshot`. 31 | 32 | ``` 33 | install myPackage@1.2.3-snapshot 34 | ``` 35 | 36 | The reason we store it in the artifacts directory is because it might still get used if you attempt to do an offline install. CommandBox will check the artifacts folder as a last-ditch attempt if ForgeBox is down. 37 | 38 | ## Custom Artifacts Directory 39 | 40 | You can control where your artifact cache is stored with the `artifactsDirectory` config setting. This can be useful to keep your primary drive from filling up, or to point your files to a shared network drive that your coworkers can share. 41 | 42 | ``` 43 | config set artifactsDirectory=/path/to/artifacts 44 | ``` 45 | -------------------------------------------------------------------------------- /package-management/box.json/basic-package-data.md: -------------------------------------------------------------------------------- 1 | # Basic Package Data 2 | 3 | The following box.json properties provide basic information about what your package is. 4 | 5 | ## name 6 | 7 | **string** 8 | 9 | Name of the package. Short, but descriptive. 10 | 11 | ```bash 12 | package set name="Whiz Bang Module" 13 | package show name 14 | ``` 15 | 16 | ## slug 17 | 18 | **string** 19 | 20 | The unique slug for this package. Cannot contain spaces or special characters. Can contain a hyphen. Use the `forgebox slugcheck` command to see if this slug is already in use. This is what people will use when installing your package from ForgeBox. 21 | 22 | ```bash 23 | package set slug="whiz-bang" 24 | package show slug 25 | ``` 26 | 27 | ## version 28 | 29 | **string** 30 | 31 | The semantic version of your package following the pattern `major.minor.patch.build`. Ex: `2.3.5.0012` 32 | 33 | ```bash 34 | package set version=1.0.0.0000 35 | package show version 36 | ``` 37 | 38 | ## author 39 | 40 | **string** 41 | 42 | The name of the author of the module as a string. 43 | 44 | ```bash 45 | package set author="Brad Wood " 46 | package show author 47 | ``` 48 | 49 | ## shortDescription 50 | 51 | **string** 52 | 53 | Describes what this package is in a couple sentences. Save the dissertation for the `description`. 54 | 55 | ```bash 56 | package set description="Install this module to add a bit of Whiz Bang to your app." 57 | package show description 58 | ``` 59 | 60 | ## private 61 | 62 | **boolean** 63 | 64 | A flag that designates if this package is a ForgeBox private package. ForgeBox private packages are not publicly accessible, but offer all the benefits of ForgeBox. Private packages will be a paid feature for ForgeBox Pro subscribers, though the feature is currently available to all users for free. 65 | 66 | ```bash 67 | package set private=false 68 | package show private 69 | ``` 70 | -------------------------------------------------------------------------------- /package-management/box.json/dependencies.md: -------------------------------------------------------------------------------- 1 | # Dependencies 2 | 3 | ## dependencies 4 | 5 | **object** 6 | 7 | This object tracks the other packages that are required to run the project. Packages are added here automatically by the `install ID` command, but you can also manually add them and just type `install` to install them. 8 | 9 | The key is the unique slug of the package and the value is the a semvar range, local directory, URL to a zip, or a source control URL. 10 | 11 | ```javascript 12 | "dependencies" : { 13 | "coldbox" : "x" // latest version from ForgeBox 14 | "cborm" : "1.0.1", // a specific version from ForgeBox 15 | "private-package" : "C:\\libs\\foo", // local folder 16 | "private-package2" : "C:\\libs\\foo.zip", // local file 17 | "baz" : "http://site.com/baz.zip", // URL to zip file 18 | "cbcsrf" : "git://github.com/ColdBox/cbox-csrf.git" // Git endpoint 19 | } 20 | ``` 21 | 22 | ```bash 23 | package set dependencies="{ coldbox : '4.0.0' }" --append 24 | package show dependencies 25 | ``` 26 | 27 | ## devDependencies 28 | 29 | **object** 30 | 31 | Development dependencies operate the same as regular ones, expect they are not required to use this project. Instead, they are only required if you plan to do development on the project. These usually including testing libraries, etc. 32 | 33 | The `install` command will save dependencies here when you use the `--saveDev` flag. These packages will be skipped when you run `install --production` 34 | 35 | ```javascript 36 | "devDependencies" : { 37 | "testbox" : "2.0" 38 | } 39 | ``` 40 | 41 | ```bash 42 | package set devDependencies="{ cbdebugger : '1.0.0' }" --append 43 | package show devDependencies 44 | ``` 45 | -------------------------------------------------------------------------------- /package-management/box.json/embedded-server.md: -------------------------------------------------------------------------------- 1 | # Embedded Server 2 | 3 | These properties affect how the embedded server starts. These settings are now deprecated in favor of the new server.json file. 4 | 5 | ## defaultPort 6 | 7 | **number** 8 | 9 | This is the HTTP port the server will be started on when you use the `start` command. Specifying the `port` parameter on the `start` command will override this. 10 | 11 | ```bash 12 | package set defaultPort=8080 13 | package show defaultPort 14 | ``` 15 | 16 | This setting is deprecated in favor of the `port` property of `server.json`. CommandBox will use this setting still if there is no port in server.json and a port argument is not specified with the `start` command. 17 | 18 | ## engines 19 | 20 | **array of objects** 21 | 22 | This represents a list of CF engines your project supports and their version with a semvar range. 23 | 24 | ```javascript 25 | "engines" : [ 26 | { "type" : "railo", "version" : ">=4.2.1" }, 27 | { "type" : "adobe", "version" : ">=10.0.0" } 28 | ] 29 | ``` 30 | 31 | ```bash 32 | package set engines="[ { type : 'lucee', version : '>=4.5.x' } ]" --append 33 | package show engines 34 | ``` 35 | 36 | _This data is informational only and not yet used by the embedded server_ 37 | 38 | ## defaultEngine 39 | 40 | **string** 41 | 42 | The default CF engine for the `start` command to use. 43 | 44 | ```bash 45 | package set defaultEngine=lucee 46 | package show defaultEngine 47 | ``` 48 | 49 | _This data is informational only and not yet used by the embedded server_ 50 | -------------------------------------------------------------------------------- /package-management/box.json/package-urls.md: -------------------------------------------------------------------------------- 1 | # Package URLs 2 | 3 | There are a number of URLs associated with your package that you can specify with these properties. 4 | 5 | ## location 6 | 7 | **string** 8 | 9 | The location of where to download this package. Needs to point to a zip file containing the package. 10 | 11 | ```bash 12 | package set location="https://github.com/ColdBox/coldbox-platform/archive/master.zip" 13 | package show location 14 | ``` 15 | 16 | ## homepage 17 | 18 | **string** 19 | 20 | The homepage for your product. It's fine if this is just the GitHub page. A nice readme can make for a good homepage. 21 | 22 | ```bash 23 | package set homepage="http://www.coldbox.org" 24 | package show homepage 25 | ``` 26 | 27 | ## documentation 28 | 29 | **string** 30 | 31 | This is where users can go to find documentation on how to use your package. Can be a wiki, HTML docs, etc. 32 | 33 | ```bash 34 | package set documentation="http://wiki.coldbox.org" 35 | package show documentation 36 | ``` 37 | 38 | ## repository 39 | 40 | **object** 41 | 42 | This describes the repository used for source control with this package. Object needs a `type` and `URL` key. Examples of `type` would be Git, SVN, Mercurial, etc. 43 | 44 | ```javascript 45 | "repository" : { 46 | "type" : "Git", 47 | "URL" : "https://github.com/ColdBox/coldbox-platform.git" 48 | } 49 | ``` 50 | 51 | ```bash 52 | package set repository="{ type : 'Git', URL : 'https://github.com/ColdBox/coldbox-platform.git' }" 53 | package show repository 54 | ``` 55 | 56 | ## bugs 57 | 58 | **string** 59 | 60 | This is the URL where developers can go to report bugs in your package. We know you NEVER write bugs in your software, but it's just a formality so humor us :) 61 | 62 | ```bash 63 | package set bugs="https://ortussolutions.atlassian.net" 64 | package show bugs 65 | ``` 66 | 67 | ## projectURL 68 | 69 | **string** 70 | 71 | This is the URL you visit to browse to this actual project code once it is running. 72 | 73 | ```bash 74 | package set projectURL="http://localhost" 75 | package show projectURL 76 | ``` 77 | -------------------------------------------------------------------------------- /package-management/box.json/testbox.md: -------------------------------------------------------------------------------- 1 | # TestBox 2 | 3 | ## testbox 4 | 5 | **object** 6 | 7 | This object stored configuration information used by the TestBox BDD and xUnit testing library. The data is accessed by commands in the `testbox` command namespace. 8 | 9 | ### testbox.runner 10 | 11 | **string** or **array** 12 | 13 | `testbox.runner` can be a simple string that contains the full runner URL. 14 | 15 | ```javascript 16 | "testbox" : { 17 | "runner" : "http://localhost/tests/runner.cfm" 18 | } 19 | ``` 20 | 21 | ```bash 22 | package set testbox.runner="http://localhost/tests/runner.cfm" 23 | package show testbox.runner 24 | testbox run 25 | ``` 26 | 27 | `testbox.runner` can alternatively be an array of objects containing "named" runner URLs. 28 | 29 | ```javascript 30 | "testbox" : { 31 | "runner" : [ 32 | { "cf11" : "http://cf9.localhost/tests/runner.cfm" }, 33 | { "lucee" : "http://railo.localhost/tests/runner.cfm" } 34 | ] 35 | } 36 | ``` 37 | 38 | ```bash 39 | package set testbox.runner="[ { default : 'http://localhost/tests/runner.cfm' } ]" --append 40 | package show testbox.runner 41 | testbox run default 42 | ``` 43 | 44 | ## More... 45 | 46 | Our box.json template shows other placeholder properties inside the `testbox` object, but only `runner` is implemented for now. 47 | 48 | _In the future, the_ `testbox` _object may be moved into a separate JSON file for organizational purposes._ 49 | -------------------------------------------------------------------------------- /package-management/code-endpoints/README.md: -------------------------------------------------------------------------------- 1 | # Code Endpoints 2 | 3 | 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. 4 | 5 | ## Supported Endpoints 6 | 7 | Here is a list of the package endpoints currently supported by CommandBox. 8 | 9 | * **ForgeBox** - Cloud-based packages [(_Read more_)](forgebox.md) 10 | * **HTTP(S)** - Point to a hosted zip file containing a package [(_Read more_)](http-s.md) 11 | * **File** - A local file containing a package [(_Read more_)](file.md) 12 | * **Folder** - A local folder containing a package [(_Read more_)](folder.md) 13 | * **Git** - Any Git repo containing a package [(_Read more_)](git.md) 14 | * **Java** - Install OpenJDK for your servers [(Read more)](java.md) 15 | * **Jar** - A jar file hosted via HTTP that's _not_ contained in a zip file [(_Read more_)](jar-via-http.md) 16 | * **Lex**- A Lucee Extension hosted via HTTP that's _not_ contained in a zip file [(_Read more_)](lex-via-http.md) 17 | * **S3** - A package zip stored in a private S3 bucket [(_Read more_)](s3.md) 18 | * **CFLib** - UDFs posted on CFLib.org [(_Read more_)](cflib.md) 19 | * **Gist** - A package hosted as a Gist from gist.github.com [(_Read more_)](gist.md) 20 | 21 | ## Examples 22 | 23 | ```bash 24 | install coldbox@3.8.1 25 | install http://www.site.com/myPackage.zip 26 | install /var/libs/myPackage.zip 27 | install /var/libs/myPackage/ 28 | install git://github.com/username/repoName.git#v1.5.6 29 | ``` 30 | -------------------------------------------------------------------------------- /package-management/code-endpoints/file.md: -------------------------------------------------------------------------------- 1 | # File 2 | 3 | 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. 4 | 5 | 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. 6 | 7 | ## Installation 8 | 9 | To install a package from a local file, use the path like so: 10 | 11 | ```bash 12 | install /var/libs/myPackage.zip 13 | ``` 14 | 15 | Note if using Windows, you need to escape backslashes in the command parameter. 16 | 17 | ```bash 18 | install C:\\websites\libs\\myPackage.zip 19 | ``` 20 | 21 | Relative paths will start in the directory where the command is being run from. 22 | 23 | ```bash 24 | install libs/myPackage.zip 25 | install ../../libs/myPackage2.zip 26 | ``` 27 | 28 | ## In box.json 29 | 30 | You can specify packages from file endpoints as dependencies in your `box.json` in this format. Remember, JSON requires that backslashes be escaped. 31 | 32 | ```javascript 33 | { 34 | "dependencies" : { 35 | "myPackage" : "/var/libs/myPackage.zip" 36 | "myPackage2" : "C:\\websites\libs\\myPackage2.zip" 37 | } 38 | } 39 | ``` 40 | -------------------------------------------------------------------------------- /package-management/code-endpoints/folder.md: -------------------------------------------------------------------------------- 1 | # Folder 2 | 3 | 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. 4 | 5 | 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. 6 | 7 | ## Installation 8 | 9 | To install a package from a local folder, use the path like so: 10 | 11 | ```bash 12 | install /var/libs/myPackage/ 13 | ``` 14 | 15 | Note if using Windows, you need to escape backslashes in the command parameter. 16 | 17 | ```bash 18 | install C:\\websites\libs\\myPackage\\ 19 | ``` 20 | 21 | Relative paths will start in the directory where the command is being run from. 22 | 23 | ```bash 24 | install libs/myPackage/ 25 | install ../../libs/myPackage2/ 26 | ``` 27 | 28 | ## In box.json 29 | 30 | You can specify packages from folder endpoints as dependencies in your `box.json` in this format. Remember, JSON requires that backslashes be escaped. 31 | 32 | ```javascript 33 | { 34 | "dependencies" : { 35 | "myPackage" : "/var/libs/myPackage/" 36 | "myPackage2" : "C:\\websites\libs\\myPackage\\" 37 | } 38 | } 39 | ``` 40 | -------------------------------------------------------------------------------- /package-management/code-endpoints/gist.md: -------------------------------------------------------------------------------- 1 | # Gist 2 | 3 | CommandBox can install a Github Gist from [gist.github.com](https://gist.github.com/) as a package. 4 | 5 | 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. 6 | 7 | ## Installation 8 | 9 | To install a package from a Github Gist, you must pass the Gist ID from gist.github.com: 10 | 11 | ```bash 12 | install gist: 13 | install gist:b6cfe92a08c742bab78dd15fc2c1b2bb 14 | ``` 15 | 16 | The Github username is optional. 17 | 18 | ```bash 19 | install gist:/ 20 | ``` 21 | 22 | You can target a specific `commit` by adding a "commit-ish" after the Gist ID. 23 | 24 | ```bash 25 | install gist:b6cfe92a08c742bab78dd15fc2c1b2bb#37348a126f1f410120785be0d84ad7a2148c3e9f 26 | ``` 27 | 28 | ## In box.json 29 | 30 | You can specify packages from folder endpoints as dependencies in your `box.json` in this format. Remember, JSON requires that backslashes be escaped. 31 | 32 | ```javascript 33 | { 34 | "dependencies" : { 35 | "myPackage" : "gist:gistID" 36 | } 37 | } 38 | ``` 39 | -------------------------------------------------------------------------------- /package-management/code-endpoints/http-s.md: -------------------------------------------------------------------------------- 1 | # HTTP(S) 2 | 3 | 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. 4 | 5 | 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: 6 | 7 | 1. If the URL has the zip file name in it, the name without ".zip" is used. 8 | 2. If the URL contains `github.com`, the repo name will be used. 9 | 3. Otherwise, the entire URL will have non alpha-numeric characters removed and used. 10 | 11 | ## Installation 12 | 13 | To install a package from a website, use the full URL like so: 14 | 15 | ```bash 16 | install http://www.site.com/myPackage.zip 17 | ``` 18 | 19 | ## In box.json 20 | 21 | You can specify packages from HTTP(S) endpoints as dependencies in your `box.json` in this format: 22 | 23 | ```javascript 24 | { 25 | "dependencies" : { 26 | "myPackage" : "http://www.site.com/myPackage.zip" 27 | } 28 | } 29 | ``` 30 | 31 | ## Cached URLs 32 | 33 | 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. 34 | 35 | ```bash 36 | install https+cached://downloads.ortussolutions.com/ortussolutions/coldbox-modules/cbi18n/1.4.0/cbi18n-1.4.0.zip 37 | ``` 38 | 39 | Or 40 | 41 | ```bash 42 | start cfengine=http+cached://update.lucee.org/rest/update/provider/forgebox/5.3.3.60-RC 43 | ``` 44 | 45 | Cached artifacts will be stored under the slug `HTTP_Cached` and can be viewed like so: 46 | 47 | ```bash 48 | artifacts list HTTP_Cached 49 | ``` 50 | -------------------------------------------------------------------------------- /package-management/code-endpoints/jar-via-http.md: -------------------------------------------------------------------------------- 1 | # Jar (via HTTP) 2 | 3 | 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). 4 | 5 | ``` 6 | install jar:http://site.com/path/to/file.jar 7 | install "jar:https://github.com/coldbox-modules/cbox-bcrypt/blob/master/modules/bcrypt/models/lib/jbcrypt.jar?raw=true" 8 | install "jar:https://search.maven.org/remotecontent?filepath=jline/jline/3.0.0.M1/jline-3.0.0.M1.jar" 9 | ``` 10 | 11 | ## Installation path 12 | 13 | Files from the `jar:` endpoint will be placed in a `lib/` folder by default unless you provide another folder for installation. 14 | 15 | ## In box.json 16 | 17 | You can specify jars as dependencies in your `box.json` in this format. 18 | 19 | ```javascript 20 | { 21 | "dependencies":{ 22 | "jline-3.0.0.M1":"jar:https://search.maven.org/remotecontent?filepath=jline/jline/3.0.0.M1/jline-3.0.0.M1.jar" 23 | } 24 | } 25 | ``` 26 | 27 | Note this installation method does not include any dependencies of the jar like a Maven installation would. That will be a future endpoint. 28 | 29 | ## Semantic Versioning 30 | 31 | The jar endpoint will make the following assumptions about what version of a jar a particular URL may point to: 32 | 33 | * It tries and parse a semantic version from the URL's path 34 | * It will store that version in the package's box.json (`0.0.0` if not found) 35 | * It will use that version when checking for updates to the jar 36 | 37 | This will be reflected in what you see in the **package list** and **outdated** commands. 38 | 39 | So for example, if you install a jar dependency like so: 40 | 41 | ```bash 42 | install jar:https://repo1.maven.org/maven2/co/elastic/apm/elastic-apm-agent/1.24.0/elastic-apm-agent-1.24.0.jar 43 | ``` 44 | 45 | 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. 46 | -------------------------------------------------------------------------------- /package-management/code-endpoints/lex-via-http.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: Lucee Extensions 3 | --- 4 | 5 | # Lex (via HTTP or File) 6 | 7 | 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. 8 | 9 | ``` 10 | install lex:https://server.com/path/to/ortus-redis-cache-1.4.0.lex 11 | ``` 12 | 13 | The Lex endpoint can also be used to install local lex files. 14 | 15 | ```bash 16 | install lex:C:\path\to\my.lex 17 | install lex:/path/to/my.lex 18 | # Windows UNC path 19 | install lex:\\\\serverName\sharename\my.lex 20 | ``` 21 | 22 | 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. 23 | 24 | ``` 25 | install 5C558CC6-1E67-4776-96A60F9726D580F1 26 | ``` 27 | 28 | ## Installation Path 29 | 30 | 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. 31 | 32 | ## In box.json 33 | 34 | You can specify a lex as dependencies in your `box.json` in this format. 35 | 36 | ```javascript 37 | { 38 | "dependencies":{ 39 | "ortus-redis-cache-1.4.0":"lex:https://server.com/path/to/ortus-redis-cache-1.4.0.lex" 40 | } 41 | } 42 | ``` 43 | 44 | This means you can run a `box install` on a fresh project to pull down extensions needed for your app to run. 45 | -------------------------------------------------------------------------------- /package-management/dependencies.md: -------------------------------------------------------------------------------- 1 | # Dependencies 2 | 3 | Dependencies are other packages that are required by another package for it to run. A simple package may have no dependencies, or it may have many. There are two types of dependencies: a regular **dependency** or a **development dependency**. Regular dependencies are ones required for operation of the main package. Development dependencies are optional and only necessary if you plan on making changes to the package you're installing. Dev dependencies would include testing frameworks or build tools. 4 | 5 | When a package is installed, CommandBox will read its dependencies (from the box.json) and recursively install them as well. This encourages developers to write small, reusable libraries for everyone to use. When installing via a package manager, you don't have to worry about getting all the pieces installed. 6 | 7 | Dependencies and development dependencies are stored in an object with the slug for the key and a version range for the value. The are several options available for these version ranges and more information can be found in the section on [Semantic versioning](semantic-versioning.md). 8 | 9 | ```bash 10 | "dependencies":{ 11 | "coldbox-be":"3.0.0", 12 | "cbvalidation":"1.0.0" 13 | "cborm":"1.0.0" 14 | }, 15 | "devDependencies":{ 16 | "testbox":"2.0.0" 17 | }, 18 | ``` 19 | 20 | When you install a dependency , it will be automatically added to your box.json. Use the `--saveDev` flag to save a development dependency. Uninstalling a dependency will remove it from your box.json unless you set the `save` parameter to false. 21 | 22 | When you distribute a package for others to use, you should omit it dependencies. This will reduce the size of your repository and will prevent you from having to mess with the 3rd party code. As long as they are saved in your box.json, you're good. 23 | 24 | When someone installs your package, CommandBox will automatically get the latest dependencies for them. If you're sharing an entire project that other people will download or clone from GitHub, they can simply run the `install` command with no parameters. 25 | 26 | ```bash 27 | install 28 | ``` 29 | 30 | This basically installs the root box.json as the current package, which means all dependencies that don't exist already will be installed. Now your project should be assembled and ready to run! 31 | -------------------------------------------------------------------------------- /package-management/installing-packages/debug-installation.md: -------------------------------------------------------------------------------- 1 | # Debug Installation 2 | 3 | There is a helpful command called `forgebox version-debug` which will show you what version of a package will be installed without actually installing it. It can also be useful to test a semver range and see what packages it matches. 4 | 5 | So, for example, if you wanted to see what ColdBox version would be installed if you were to run 6 | 7 | ```bash 8 | install coldbox@6.x 9 | ``` 10 | 11 | then you can instead run this 12 | 13 | ```bash 14 | forgebox version-debug coldbox@6.x 15 | ``` 16 | 17 | You will see output similar to this: 18 | 19 |
20 | 21 | In order to filter the output to only show versions which matched your semantic version, use the `--showMatchesOnly` flag 22 | 23 | ```bash 24 | forgebox version-debug coldbox@6.x --showMatchesOnly 25 | ``` 26 | 27 |
28 | -------------------------------------------------------------------------------- /package-management/installing-packages/installation-options.md: -------------------------------------------------------------------------------- 1 | # Installation Options 2 | 3 | There are several options you can use to control how a package is installed. 4 | 5 | ## Saving dependencies 6 | 7 | By default, any package you install will be saved as a dependency. To save it as a development dependency instead, use the `--saveDev` flag. 8 | 9 | ```bash 10 | install testbox --saveDev 11 | ``` 12 | 13 | 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`. 14 | 15 | ```bash 16 | install cborm --!save 17 | ``` 18 | 19 | ## Production Installation 20 | 21 | 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 `ignore` property in its box.json. 22 | 23 | ```bash 24 | install cbvalidation --production 25 | ``` 26 | 27 | ## Verbose Installation 28 | 29 | 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. 30 | 31 | ```bash 32 | install cbi18n --verbose 33 | ``` 34 | 35 | ## Forced Installation 36 | 37 | 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. 38 | 39 | ```bash 40 | install cbsoap --force 41 | ``` 42 | -------------------------------------------------------------------------------- /package-management/private-packages.md: -------------------------------------------------------------------------------- 1 | # Private Packages 2 | 3 | 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. 4 | 5 | ## Publishing private packages to ForgeBox 6 | 7 | To create a private package, set the `private` property to `true` in your `box.json` prior to publishing. 8 | 9 | ``` 10 | package init 11 | package set private=true 12 | package set slug=my-slug@forgeBoxUser 13 | etc... 14 | publish 15 | ``` 16 | 17 | ## Installing private packages from ForgeBox 18 | 19 | Replace `forgeBoxUser` with your actual ForgeBox username. When you install the package, you'll need to use the full slug like so: 20 | 21 | ``` 22 | install my-slug@forgeBoxUser 23 | ``` 24 | 25 | You can install specific versions or version ranges as you would expect: 26 | 27 | ``` 28 | install my-slug@forgeBoxUser@1.0.0 29 | install my-slug@forgeBoxUser@be 30 | ``` 31 | 32 | > Private packages will be a paid feature for ForgeBox Pro subscribers, though the feature is currently available to all users for free. 33 | -------------------------------------------------------------------------------- /package-management/system-modules.md: -------------------------------------------------------------------------------- 1 | # System Modules 2 | 3 | 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. 4 | 5 | ``` 6 | install commandbox-fusionreactor 7 | ``` 8 | 9 | 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. 10 | 11 | ``` 12 | package list --system 13 | package update --system 14 | package uninstall commandbox-fusionreactor --system 15 | ``` 16 | 17 | The package commands that accept a `--system` flag are as follows: 18 | 19 | * package install 20 | * package uninstall 21 | * package outdated 22 | * package list 23 | * package update 24 | * package show 25 | * package set 26 | * package clear 27 | -------------------------------------------------------------------------------- /release-history/1.x-versions/README.md: -------------------------------------------------------------------------------- 1 | # 1.x Versions 2 | 3 | In this section you will find the release notes for the 1.x version of CommandBox. 4 | 5 | * [Version 1.0.0](whats-in-1.0.0.md) - Feb 2015 6 | -------------------------------------------------------------------------------- /release-history/2.x-versions/README.md: -------------------------------------------------------------------------------- 1 | # 2.x Versions 2 | 3 | In this section you will find the release notes for the 2.x version of CommandBox. 4 | 5 | * [Version 2.2.0](whats-new-in-2.2.0.md) - Nov 2015 6 | * [Version 2.1.1](whats-new-in-2.1.1.md) - Aug 2015 7 | * [Version 2.1.0](whats-new-in-2.1.0.md) - Aug 2015 8 | * [Version 2.0.0](whats-new-in-2.0.0.md) - June 2015 9 | 10 | -------------------------------------------------------------------------------- /release-history/2.x-versions/whats-new-in-2.1.1.md: -------------------------------------------------------------------------------- 1 | # What's New in 2.1.1 2 | 3 | This fixes a bug in the "update" and "outdated" commands that caused them to error after you had installed packages from an endpoint other than ForgeBox. Note, packages installed from HTTP(S) and Git endpoints will always show as outdated and will always update since those endpoints don't provide a way to know what version they're hosting without downloading the entire package anyway. 4 | 5 | We also included a small enhancement to the Git endpoint to allow for authentication via public/private SSH keys. As long as you have a public key configured on your Git server and the private key is stored in \~/.ssh/ using a standard name, SSH-based clones should automatically authenticate. Please see [the docs](http://commandbox.ortusbooks.com/content/packages/endpoints/git.html) for more info. 6 | 7 | As always, the [CommandBox Getting Started Guide](http://commandbox.ortusbooks.com/content/getting_started_guide.html) is located here: 8 | 9 | [http://commandbox.ortusbooks.com/content/getting\_started\_guide.html](http://commandbox.ortusbooks.com/content/getting_started_guide.html) 10 | 11 | ## Release Notes 12 | 13 | ### Bug 14 | 15 | * \[[COMMANDBOX-259](https://ortussolutions.atlassian.net/browse/COMMANDBOX-259)] - update command erroring 16 | 17 | ### New Feature 18 | 19 | * \[[COMMANDBOX-263](https://ortussolutions.atlassian.net/browse/COMMANDBOX-263)] - Git SSH endpoint private key support 20 | 21 | ### Improvement 22 | 23 | * \[[COMMANDBOX-260](https://ortussolutions.atlassian.net/browse/COMMANDBOX-260)] - Standardize parameter names for install command 24 | -------------------------------------------------------------------------------- /release-history/3.x-versions/README.md: -------------------------------------------------------------------------------- 1 | # 3.x Versions 2 | 3 | In this section you will find the release notes for the 3.x version of CommandBox. 4 | 5 | * [Version 3.9.0](whats-new-in-3.9.0.md) - Nov 2017 6 | * [Version 3.8.0 ](whats-new-in-3.8.0.md)- Aug 2017 7 | * [Version 3.7.0](whats-new-in-3.7.0.md) - Jul 2017 8 | * [Version 3.6.0](whats-new-in-3.6.0.md) - Mar 2017 9 | * [Version 3.5.0](whats-new-in-3.5.0.md) - Jan 2017 10 | * [Version 3.4.0](whats-new-in-3.4.0.md) - Nov 2016 11 | * [Version 3.3.0](whats-new-in-3.3.0.md) - Oct 2016 12 | * [Version 3.2.0](whats-new-in-3.2.0.md) - Jul 2016 13 | * [Version 3.1.1](whats-new-in-3.1.1.md) - Jul 2016 14 | * [Version 3.0.1](whats-new-in-3.0.1.md) - Feb 2016 15 | * [Version 3.0.0](whats-new-in-3.0.0.md) - Feb 2016 16 | 17 | -------------------------------------------------------------------------------- /release-history/3.x-versions/whats-new-in-3.0.1.md: -------------------------------------------------------------------------------- 1 | # What's New in 3.0.1 2 | 3 | Properties weren't being read correctly from the `server.json` file. If you have been using `server.json`, please double check the format of the file here in our docs: 4 | 5 | [http://commandbox.ortusbooks.com/content/embedded\_server/serverjson.html](http://commandbox.ortusbooks.com/content/embedded_server/serverjson.html) 6 | 7 | This fix will make this functionality work as expected: 8 | 9 | ``` 10 | server set web.http.port=8000 11 | server start 12 | ``` 13 | 14 | ## Upgrading 15 | 16 | If you already have 3.0.0 then this fix only affects the CFML bits and is very easy for you to install. Simply run this command: 17 | 18 | ``` 19 | upgrade 20 | ``` 21 | 22 | If you're still on CommandBox 2.x, check out our [3.0.0 release announcement](https://www.ortussolutions.com/blog/commandbox-300-final-released) to see the cool new stuff. 23 | -------------------------------------------------------------------------------- /release-history/3.x-versions/whats-new-in-3.8.0.md: -------------------------------------------------------------------------------- 1 | # What's New in 3.8.0 2 | 3 | ### Bug 4 | 5 | * \[[COMMANDBOX-665](https://ortussolutions.atlassian.net/browse/COMMANDBOX-665)] - Relative SSL certFile or keyFile path in server.json isn't expanded 6 | * \[[COMMANDBOX-674](https://ortussolutions.atlassian.net/browse/COMMANDBOX-674)] - propertyfile set errors if file doesn't exist 7 | 8 | ### New Feature 9 | 10 | * \[[COMMANDBOX-675](https://ortussolutions.atlassian.net/browse/COMMANDBOX-675)] - Allow relative property file paths in task runners 11 | 12 | ### Improvement 13 | 14 | * \[[COMMANDBOX-666](https://ortussolutions.atlassian.net/browse/COMMANDBOX-666)] - Allow custom tray contributions to have relative image path 15 | * \[[COMMANDBOX-667](https://ortussolutions.atlassian.net/browse/COMMANDBOX-667)] - Improve coldbox create app --wizard 16 | * \[[COMMANDBOX-671](https://ortussolutions.atlassian.net/browse/COMMANDBOX-671)] - Always run onServerInstall 17 | * \[[COMMANDBOX-672](https://ortussolutions.atlassian.net/browse/COMMANDBOX-672)] - add getInstance() to base interceptor class 18 | * \[[COMMANDBOX-673](https://ortussolutions.atlassian.net/browse/COMMANDBOX-673)] - Improve handling of loading a bad modules 19 | * \[[COMMANDBOX-678](https://ortussolutions.atlassian.net/browse/COMMANDBOX-678)] - Command to normalize line endings for a batch of files 20 | * \[[COMMANDBOX-679](https://ortussolutions.atlassian.net/browse/COMMANDBOX-679)] - Improve package parsing regex for private packages 21 | -------------------------------------------------------------------------------- /release-history/4.x-versions/README.md: -------------------------------------------------------------------------------- 1 | # 4.x Versions 2 | 3 | In this section you will find the release notes for the 4.x version of CommandBox. 4 | 5 | * [Version 4.8.0](whats-new-in-4.8.0.md) - Sept 2019 6 | * [Version 4.7.0](whats-new-in-4.7.0.md) - June 2019 7 | * [Version 4.6.0](whats-new-in-4.6.0.md) - Mar 2019 8 | * [Version 4.5.0](whats-new-in-4.5.0.md) - Dec 2018 9 | * [Version 4.4.0](whats-new-in-4.4.0.md) - Nov 2018 10 | * [Version 4.3.0](whats-new-in-4.3.0.md) - Oct 2018 11 | * [Version 4.2.0](whats-new-in-4.2.0.md) - Aug 2018 12 | * [Version 4.1.0](whats-new-in-4.1.0.md) - Jun 2018 13 | * [Version 4.0.0](whats-new-in-4.0.0.md) - Jun 2018 14 | -------------------------------------------------------------------------------- /release-history/5.x-versions/README.md: -------------------------------------------------------------------------------- 1 | # 5.x Versions 2 | 3 | In this section you will find the release notes for the 5.x version of CommandBox. 4 | 5 | * [Version 5.9.1](whats-new-in-5.9.1.md) - August 2023 6 | * [Version 5.9.0](whats-new-in-5.9.0.md) - May 2023 7 | * [Version 5.8.0](whats-new-in-5.8.0.md) - April 2023 8 | * [Version 5.7.0](whats-new-in-5.7.0.md) - December 2022 9 | * [Version 5.6.0](whats-new-in-5.6.0.md) - September 2022 10 | * [Version 5.5.2](whats-new-in-5.5.2.md) - May 2022 11 | * [Version 5.5.1](whats-new-in-5.5.1.md) - May 2022 12 | * [Version 5.4.2](whats-new-in-5.4.2.md) - October 2021 13 | * [Version 5.4.1](whats-new-in-5.4.1.md) - September 2021 14 | * [Version 5.4.0](whats-new-in-5.4.0.md) - August 2021 15 | * [Version 5.3.0](whats-new-in-5.3.0.md) - May 2021 16 | * [Version 5.2.1](whats-new-in-5.2.1.md) - Dec 2020 17 | * [Version 5.2.0 ](whats-new-in-5.2.0.md)- Nov 2020 18 | * [Version 5.1.1](whats-new-in-5.1.1.md) - June 2020 19 | * [Version 5.1.0](whats-new-in-5.1.0.md) - May 2020 20 | * [Version 5.0.0](whats-new-in-5.0.0.md) - Mar 2020 21 | -------------------------------------------------------------------------------- /release-history/5.x-versions/whats-new-in-5.1.1.md: -------------------------------------------------------------------------------- 1 | # What's New in 5.1.1 2 | 3 | This release was primarily to address a regression in 5.1.0 affecting Mac OS users who tried to start Lucee servers. If you see an error similar to this on a Lucee server and you're running a Mac and CommandBox 5.1.0, then this release will fix it for you. 4 | 5 | ``` 6 | lucee.runtime.exp.NativeException: mac os x is not a supported OS platform. 7 | ``` 8 | 9 | If you are upgrading from CommandBox 5.1.0, there are only a handful of tickets which are listed below. If you are updating from an earlier version of CommandBox, please check out our [5.0.0](https://www.ortussolutions.com/blog/commandbox-500-released) and [5.1.0](https://www.ortussolutions.com/blog/commandbox-510-released) release blogs. 10 | 11 | ## Release notes 12 | 13 | ### Bug 14 | 15 | * \[[COMMANDBOX-1107](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1107)] - Overzealous gitignore matching of parent directories when zipping up for ForgeBox storage 16 | * \[[COMMANDBOX-1173](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1173)] - Enabling SSL results in some CFHTTP requests to fail. 17 | * \[[COMMANDBOX-1178](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1178)] - writedump failing in Lucee 18 | * \[[COMMANDBOX-1179](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1179)] - File globbing matching partial file names 19 | 20 | ### Improvement 21 | 22 | * \[[COMMANDBOX-1181](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1181)] - Allow for verbose startup without debug logging of requests 23 | -------------------------------------------------------------------------------- /release-history/5.x-versions/whats-new-in-5.4.1.md: -------------------------------------------------------------------------------- 1 | # What's New in 5.4.1 2 | 3 | ## Release Notes 4 | 5 | Bug 6 | 7 | [COMMANDBOX-1374](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1374) Some installs unnecessarily write to the box.json 8 | 9 | [COMMANDBOX-1370](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1370) ConfigService::settingExists() fails in race conditions due to non-varscoped variables in JSONService 10 | 11 | ### Improvement 12 | 13 | [COMMANDBOX-1372](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1372) Support excludePaths in watcher DSL and watch command 14 | 15 | [COMMANDBOX-1369](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1369) Ensure Adobe wars have a seeds.properties file 16 | 17 | [COMMANDBOX-1368](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1368) Add tab complete for "env clear" command 18 | 19 | [COMMANDBOX-1367](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1367) Ignore empty startScript on server start 20 | -------------------------------------------------------------------------------- /release-history/5.x-versions/whats-new-in-5.4.2.md: -------------------------------------------------------------------------------- 1 | # What's New in 5.4.2 2 | 3 | * There is a fix for a regression introduced in 5.4.0 where updating the version of a CF engine doesn't work without forgetting the server first. 4 | * There is also an important security improvement to CommandBox servers. Thanks to Abram Adams for reporting this to Ortus so we could address it. 5 | 6 | ## Release notes 7 | 8 | Note, the details of the security improvement have been tracked privately. 9 | 10 | #### Bug 11 | 12 | [COMMANDBOX-1382](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1382) Java path shows up twice in "server info --verbose" 13 | 14 | [COMMANDBOX-1381](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1381) Updating server in-place keeps old web.xml path 15 | 16 | [COMMANDBOX-1375](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1375) recipe with multiple "install" instructions fails 17 | 18 | #### Improvement 19 | 20 | [COMMANDBOX-1380](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1380) Add additional interceptData to server interceptors 21 | 22 | [COMMANDBOX-1379](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1379) Update to WireBox 6.5.2 23 | 24 | [COMMANDBOX-1376](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1376) Immediately activate modules after installation 25 | 26 | [COMMANDBOX-1349](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1349) Improve multiselect DSL 27 | 28 | #### Story 29 | 30 | [COMMANDBOX-1120](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1120) Add JSON and Properties output for info command 31 | -------------------------------------------------------------------------------- /release-history/5.x-versions/whats-new-in-5.5.2.md: -------------------------------------------------------------------------------- 1 | # What's New in 5.5.2 2 | 3 | ### Release notes 4 | 5 | #### Bug 6 | 7 | [COMMANDBOX-1475](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1475) Server shutdowns aren't always done cleanly 8 | 9 | [COMMANDBOX-1474](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1474) Don't prompt on already-running server when terminal isn't interactive 10 | 11 | [COMMANDBOX-1472](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1472) Globber copyTo() command mishandles \*nix leading slash 12 | 13 | [COMMANDBOX-1470](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1470) preServerStart can no longer affect server.json env var replacements 14 | 15 | [COMMANDBOX-1467](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1467) Servers can no longer override rest mappings 16 | 17 | [COMMANDBOX-1465](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1465) Corruption in interactive job output 18 | 19 | [COMMANDBOX-1464](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1464) Can't set XNIO socket settings or Sequence types 20 | 21 | [COMMANDBOX-1463](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1463) Command chaining has a code path where "job" variable is not defined 22 | 23 | [COMMANDBOX-1462](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1462) cfpm breaks in single server mode 24 | 25 | #### Improvement 26 | 27 | [COMMANDBOX-1473](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1473) Allow Undertow's resource manager file system watcher to be disabled 28 | 29 | [COMMANDBOX-1468](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1468) Customize Undertow's enabled SSL protocols 30 | 31 | #### Task 32 | 33 | [COMMANDBOX-1476](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1476) Update to Lucee 5.3.9.141 stable 34 | -------------------------------------------------------------------------------- /release-history/5.x-versions/whats-new-in-5.9.1.md: -------------------------------------------------------------------------------- 1 | # What's New in 5.9.1 2 | 3 | This is a very small release with two changes. 4 | 5 | * Update to Lucee 5.4.3.2 6 | * Update bundled JRE to 11.0.20+8 7 | 8 | Note Lucee 5.4.3.2 contains critical security patches which are outlined here: 9 | 10 | [https://dev.lucee.org/t/lucee-critical-security-alert-august-15th-2023-cve-2023-38693/12893](https://dev.lucee.org/t/lucee-critical-security-alert-august-15th-2023-cve-2023-38693/12893) 11 | 12 | The new Lucee version affects the core CLI runtime as well as the default server you get when running "server start" with no cfengine specified. Possible compatibility issues related to the major bump in Lucee version: 13 | 14 | * This Lucee version does not include Hibernate, so the Ortus Hibernate extension is installed. We will stop doing this in 6.0 15 | * This Lucee version has strict XML parsing settings on by default which may affect any servers you start which parse XML containing DTDs. 16 | 17 | If you do run into XML errors, this code may help you in your Application.cfc, which allows DTDs, but still disallows XML external entities (XEE). 18 | 19 | ``` 20 | this.xmlFeatures={ 21 | externalGeneralEntities: false, 22 | disallowDoctypeDecl: false 23 | }; 24 | ``` 25 | 26 | ### Release notes 27 | 28 | #### Task 29 | 30 | * [COMMANDBOX-1609](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1609) Update bundled JRE to 11.0.20+8 31 | * [COMMANDBOX-1610](https://ortussolutions.atlassian.net/browse/COMMANDBOX-1610) Update to Lucee 5.4.3.2 32 | -------------------------------------------------------------------------------- /release-history/6.x-versions/README.md: -------------------------------------------------------------------------------- 1 | # 6.x Versions 2 | 3 | In this section you will find the release notes for the 6.x version of CommandBox. 4 | 5 | * [Version 6.0.0](whats-new-in-6.0.0.md) - February 2024 6 | * [Version 6.1.0](whats-new-in-6.1.0.md) - November 2024 7 | * [Version 6.2.0](whats-new-in-6.2.0.md) - March 2025 8 | -------------------------------------------------------------------------------- /release-history/README.md: -------------------------------------------------------------------------------- 1 | # Release History 2 | 3 | In this section you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases. 4 | 5 | * [Versions 6.x](6.x-versions/) - Feb 2024 - 6 | * [Versions 5.x](5.x-versions/) - Mar 2020 - August 2023 7 | * [Versions 4.x](4.x-versions/) - Jun 2018 - Sept 2019 8 | * [Versions 3.x](3.x-versions/) - Feb 2016 - Nov 2017 9 | * [Versions 2.x](2.x-versions/) - June 2015 - Nov 2015 10 | * [Versions 1.x](1.x-versions/) - Feb 2015 11 | -------------------------------------------------------------------------------- /setup/README.md: -------------------------------------------------------------------------------- 1 | # Setup 2 | 3 | CommandBox is a Java-based executable that will run on most recent desktop operating systems (Linux, Mac OS X, Windows). Since it is a command line tool that uses a shell interface, it does not even require an operating system using a GUI. CommandBox can be used as a development aid and automation tool alongside your favorite CFML engine and IDE, but neither of those are requirements for installation of CommandBox. 4 | -------------------------------------------------------------------------------- /setup/download.md: -------------------------------------------------------------------------------- 1 | # Download 2 | 3 | If you already have a Java JRE installed level 1.8 or higher (and set in your environment variables) you can [download](http://www.ortussolutions.com/products/commandbox#download) the non-JRE version for your Operating System. If you don't have a JRE installed or aren't sure, we would recommend you [download](http://www.ortussolutions.com/products/commandbox#download) the version with a JRE included. Below you will find the way to get the latest stable and bleeding edge releases. Please also note that in our [installation](installation.md) page you will find much more detail information on how to install CommandBox with modern Operating System package managers as well. 4 | 5 | > **Info** The non-JRE versions are all around 80MB in size, while the embedded JRE versions will go up to 120MB in size. 6 | 7 | Below you can see an image of the available downloads from the Ortus Solutions [download](http://www.ortussolutions.com/products/commandbox#download) page: 8 | 9 | ![](../.gitbook/assets/versions.png) 10 | 11 | ## Stable Release 12 | 13 | Stable versions of CommandBox can be downloaded from the downloads section of our product page. [http://www.ortussolutions.com/products/commandbox#download](http://www.ortussolutions.com/products/commandbox#download) 14 | 15 | ## Bleeding Edge 16 | 17 | We use a Jenkins integration server to automate our builds. You can download a bleeding-edge version of CommandBox directly from our integration server here: [https://downloads.ortussolutions.com/#/ortussolutions/commandbox/](https://downloads.ortussolutions.com/#/ortussolutions/commandbox/) 18 | 19 | > **Info** Keep in mind, bleeding edge builds may contain experimental features that are likely to change or bugs. 20 | 21 | ## Auto Updates 22 | 23 | Another way to get the bleeding edge version of CommandBox is to install the stable version and run our `upgrade` command using the **latest** flag. [Upgrade API docs](http://apidocs.ortussolutions.com/commandbox/current/index.html?commandbox/system/modules/system-commands/commands/upgrade.html). 24 | 25 | ```bash 26 | upgrade --latest 27 | ``` 28 | 29 | > **Info** Please note that the upgrade command will not update the main CommandBox binary. If there are major updates or you get a message about updating the binary, you will need to download the latest binary and re-install it. 30 | -------------------------------------------------------------------------------- /setup/requirements.md: -------------------------------------------------------------------------------- 1 | # Requirements 2 | 3 | Here are the requirements for installing and using CommandBox on your system. Notice some of these such as RAM and disk space depend on how many features you will plan on using. For instance, the shell only allocates about 256MB of RAM to run, but if you plan on starting embedded servers, that will spawn additional threads-- each of which will consume their own memory. 4 | 5 | ## Operating System 6 | 7 | * Windows XP+ 8 | * Mac OS 9 | * Linux 10 | 11 | ## Hardware 12 | 13 | * 256MB+ RAM 14 | * 250MB+ free hard drive space 15 | * Multi-core CPU recommended 16 | 17 | ## Software 18 | 19 | A Java JRE is listed as a software requirement, but if you have a brand new PC with no JRE we have a download option that contains the Java Runtime bundled with it. 20 | 21 | It is recommend to use Java 11, but there is preliminary support for Java 17. Keep in mind, not all CF engines support Java 17, so if you use it for the CLI, you may want to set your default server JRE to use Java 11. 22 | -------------------------------------------------------------------------------- /setup/upgrading.md: -------------------------------------------------------------------------------- 1 | # Upgrading 2 | 3 | CommandBox is a Java-based tool that involves several pieces including native Java classes, CFML code, and the embedded Railo CLI. However, most changes are confined to the CFML code managed by [WireBox](http://wiki.coldbox.org/wiki/WireBox.cfm). To determine what version you have installed, use the `version` command. 4 | 5 | ```bash 6 | box version 7 | ``` 8 | 9 | The auto-upgrade commands shown below will **not** upgrade the main CommandBox Java Binary. If there are any major upgrades to this binary, you will see a message that you will need to download the new Java binary and replace your current one. 10 | 11 | ## Stable 12 | 13 | To upgrade to the last stable version of the shell and commands, use the `upgrade` command. 14 | 15 | ```bash 16 | box upgrade 17 | ``` 18 | 19 | This command will connect to our server to determine the last stable build. If there is an upgrade, it will be downloaded and installed for you. 20 | 21 | ## Bleeding Edge 22 | 23 | To upgrade to the bleeding edge version of the shell and commands, use the **latest** flag. 24 | 25 | ```bash 26 | box upgrade --latest 27 | ``` 28 | 29 | This command will connect to our server to determine the latest build. If there is an upgrade, it will be downloaded and installed for you. 30 | 31 | ## Use The Force 32 | 33 | If you already have the latest version installed, but you still want to force an upgrade, use the **force** parameter. 34 | 35 | ```bash 36 | upgrade --force 37 | upgrade --latest --force 38 | ``` 39 | 40 | ## Brute Force 41 | 42 | Note, if you delete your `{user}/.CommandBox` folder and re-run the executable, the version of CommandBox in the executable will be unpacked regardless of any upgrades you may have installed in the mean time. On that note, another way to force an upgrade is to simply download the new executable, wipe the `.CommandBox` folder in your user directory and re-run. This will also erase any saved command history, embedded servers, or installed user commands. 43 | 44 | ## Mac/ \*Unix 45 | 46 | If you have used Hombrew to install CommandBox you must use Homebrew for any upgrade, minor or major. To upgrade CommandBox with Homebrew: 47 | 48 | ```bash 49 | brew upgrade commandbox 50 | ``` 51 | 52 | ## Linux Update 53 | 54 | (Debian) 55 | 56 | ```bash 57 | > sudo apt update 58 | 59 | > sudo apt upgrade commandbox 60 | ``` 61 | -------------------------------------------------------------------------------- /task-runners/README.md: -------------------------------------------------------------------------------- 1 | # Task Runners 2 | 3 | CommandBox allows you to automate common jobs that you want to run via Task Runners. Tasks are for when you want something more flexible than a recipe or just a simple .cfm execution. Tasks are analogous to other build tools like Ant, except you get to use CFML to build them instead of XML! Task runners are the next generation of automation for CFML developers. Now you don't need to learn another tool to improve your workflow. You can automate directly in CFML! 4 | 5 | A task is defined as a CFC and can have one or more "targets", which are declared as public methods on the CFC. This gives your task a much more well-defined API than a simple `.cfm` execution which includes proper arguments, base methods, print helpers, and portability but with very little boilerplate. Task runners operate very similar to custom commands, but instead of needing to be distributed inside a module, they are self contained in the CFC and can be dropped in any folder. 6 | 7 | ## Build your first task 8 | 9 | Let's look at how easy it is to write your first task: 10 | 11 | ``` 12 | CommandBox> task create --open 13 | ``` 14 | 15 | That will open the following new file in your default CFML IDE: 16 | 17 | ```javascript 18 | /** 19 | * Description of task 20 | */ 21 | component { 22 | 23 | /** 24 | * 25 | */ 26 | function run() { 27 | print.greenLine( 'Complete!' ); 28 | } 29 | 30 | } 31 | ``` 32 | 33 | Aaaaand, now we run it! 34 | 35 | ``` 36 | CommandBox> task run 37 | Complete! 38 | ``` 39 | 40 | That's it! The code in your `run()` method will be executed and has access to all the goodies that custom commands get like the `print` helper for easy ANSI formatting. Check out task run help for additional information on how to call a task CFC of another name, how to invoke another target method, and how to pass parameters to your tasks. 41 | -------------------------------------------------------------------------------- /task-runners/caching-task-runners.md: -------------------------------------------------------------------------------- 1 | # Caching Task Runners 2 | 3 | Every time you execute a task runner, 4 | 5 | * Lucee template cache is cleared 6 | * WireBox's metadata cache is cleared 7 | * Wirebox's mapping for the CFC is unmapped and remapped 8 | 9 | This ensure changes take affect right away, but can cause issue under load when you have multi-threaded execution of more than one task at the same time. To skip these cache clearing steps on every run for multi-threaded production use, add the following config setting. 10 | 11 | ```bash 12 | config set taskCaching=true 13 | ``` 14 | 15 | The setting defaults to **false**. 16 | -------------------------------------------------------------------------------- /task-runners/cancel-long-tasks.md: -------------------------------------------------------------------------------- 1 | # Cancel Long Tasks 2 | 3 | In CommandBox, a user can cancel a command or task by pressing Ctrl-C. This fires the interrupt handler in the terminal which calls `Thread.interrupt()` on the Java thread running in CLI. Java's interrupt doesn't kill a thread dead though, it politely asks it to wrap up what it's doing so it doesn't get messy. There are a number of built in CFML functions like `sleep()` that will automatically check and see if the thread they are executing in has been interrupted. A number of build in CommandBox functions like the print helper also check to see if the thread has been interrupted. 4 | 5 | These method throw an `InterruptedException` which aborts the execution of your task and rolls back to the interactive command prompt. But what if your task is doing a lot of work and it doesn't realize it's been asked to stop? If your task does a very large amount of computations in a loop of some kind, you can periodically check if the user has tried to interrupt you by calling this built in method that is available to all custom commands and Task Runners. 6 | 7 | ``` 8 | checkInterrupted(); 9 | ``` 10 | 11 | If the current thread hasn't been interrupted, that call will simply return immediately and you can continue with your work. If your thread has been interrupted, that call with throw an exception. No need to catch it-- the exception will automatically stop execution of your task and the CommandBox shell will catch the exception itself, output the text "CANCELLED" and return to the prompt. 12 | 13 | If you do call this method from inside of a try/catch, you'll want to rethrow any interrupted exceptions. Also, if your work has any cleanup that must always be performed like closing a socket connection, make sure you use a `finally {}` block for those items. 14 | -------------------------------------------------------------------------------- /task-runners/error-handling.md: -------------------------------------------------------------------------------- 1 | # Error Handling 2 | 3 | When a task throws an unhandled exception, any output in its print buffer will be flushed to the screen. Then the error message accompanied by a tag stack will be output to the screen and the user will be returned to the prompt. 4 | 5 | If an unexpected error happens inside a task that is non-recoverable, do not attempt to try/catch it unless you can improve the error message to something more useful. Generally speaking, just let the error bubble up and be handled by CommandBox for consistency and simplicity. 6 | 7 | ## Controlled Errors 8 | 9 | If there are expected situations such as a file not existing, that you know might go wrong, we wholeheartedly recommend checking for these situations and using the `error()` method to alert the user. Errors returned from the `error()` method will not contain any stack traces, etc. 10 | 11 | ```javascript 12 | error( "I don't like your tone of voice" ); 13 | ``` 14 | 15 | Or with an exit code: 16 | 17 | ```javascript 18 | error( message="prepare to be deleted", exitCode=666 ); 19 | ``` 20 | 21 | If you want your task to set a failing exit code, but you don't have a message to go with it, you can also simply return the exit code you want using the `return` keyword. 22 | 23 | ```javascript 24 | function run() { 25 | if( condition ) { 26 | print.greenLine( 'Well that was easy' ); 27 | } else { 28 | return 1; 29 | } 30 | } 31 | ``` 32 | -------------------------------------------------------------------------------- /task-runners/installing-lucee-extensions.md: -------------------------------------------------------------------------------- 1 | # Installing Lucee Extensions 2 | 3 | If your Task Runner requires a Lucee extension which is not already installed into the Lucee instance that powers the CLI, you will need to install it before you can use it. You can download the lex file and place it inside the `deploy` folder in the Lucee Server context inside the CLI 4 | 5 | ``` 6 | ~/.CommandBox/engine/cfml/cli/lucee-server/deploy 7 | ``` 8 | 9 | The extension will get picked up and installed within 60 seconds if CommandBox is running, or immediately on the next start. 10 | 11 | You can also use the `installExtension()` method which is part of the base Task to install any extension available on an update provider. 12 | 13 | ```javascript 14 | // MySQL JDBC Extension 15 | installExtension( '7E673D15-D87C-41A6-8B5F1956528C605F' ) 16 | ``` 17 | 18 | Or specify a version like so: 19 | 20 | ```javascript 21 | // MySQL JDBC Extension 22 | installExtension( '7E673D15-D87C-41A6-8B5F1956528C605F', '8.0.30' ) 23 | ``` 24 | -------------------------------------------------------------------------------- /task-runners/loading-ad-hoc-jars.md: -------------------------------------------------------------------------------- 1 | # Loading Ad hoc Jars 2 | 3 | If you need to use a 3rd party jar, we recommend you use the extra parameters to the createObject() function, which allows you to specify a list of jars to load from (this is a Lucee-specific feature). Read up on the `context` parameter here: 4 | 5 | {% embed url="http://docs.lucee.org/reference/functions/createobject.html" %} 6 | 7 | There are some scenarios however that don't work. One is if you need to use the `createDynamicProxy()` BIF to create CFC instances that implement Java classes that exist in an ad hoc jar. Lucee currently requires those classes to be loaded by the Lucee system classloader. 8 | 9 | As such, CommandBox gives you a mechanism to load jars into the system class loader that was used to classload Lucee so those classes are available everywhere. This is a much better and portable solution to dropping the jars in the `~/.CommandBox/lib` folder and restarting the shell. 10 | 11 | ## classLoad() 12 | 13 | To load up your custom jars on the fly, call the `classLoad()` method which is available in any custom command or Task Runner. 14 | 15 | ```javascript 16 | classLoad( 'D:/amqp-client-5.1.2.jar' ); 17 | ``` 18 | 19 | You can pass either an array or list of: 20 | 21 | * D**irectories** - All jar and class files will be loaded from each directory recursively 22 | * **Jar files** - Each jar file will be loaded 23 | * **Class files** - Each class file will be loaded 24 | 25 | Note, paths need to be absolute when you pass them in! Here's some more examples. 26 | 27 | ```javascript 28 | classLoad( 'C:/myLibs,C:/otherLibs' ); 29 | classLoad( [ 'C:/myLibs', 'C:/otherLibs' ] ); 30 | classLoad( 'C:/myLibs/myLib.jar,C:/otherLibs/other.class' ); 31 | classLoad( [ 'C:/myLibs/myLib.jar', 'C:/otherLibs/other.class' ] ); 32 | ``` 33 | -------------------------------------------------------------------------------- /task-runners/loading-ad-hoc-modules.md: -------------------------------------------------------------------------------- 1 | # Loading Ad-hoc Modules 2 | 3 | If you have a module installed to a folder that you wish to load into the CLI and use on-the-fly during a task runner, you can do so like this: 4 | 5 | ``` 6 | loadModule( 'build/modules/myUtils' ); 7 | ``` 8 | 9 | That code will load the `myUtils` module right there into the core CLI. Note, the module needs to be compatible with CommandBox. All models, interceptors, or commands inside the module will instantly be available in the CLI. 10 | 11 | This means your task runners can rely on other functionality in the form of modules which are easily distributed and shared. While you could manually install the module globally into the CLI, this method is more flexible and ad-hoc as the module is just temporarily loaded. 12 | 13 | ### Considerations 14 | 15 | * Modules aren't unloaded for you. You can do so via `ModuleService.unload( 'myUtils' )` if you like. 16 | * If a module of that name is already loaded, nothing happens. That means if you modify the module, you'll need to `reload` the shell to pick up those changes. 17 | * The path to the module can be absolute, but if relative, it will be resolved relative to the task runner CFC, not the current working directory of the shell. 18 | 19 | ### Loading Multiple Modules 20 | 21 | A task runner with an entire folder of modules to load may run into timing issues where one module requires another to be loaded before it can load. To handle this, instead of loading each module one at a time with `loadModule()` you can load an entire array of modules at ones with `loadModules()`. 22 | 23 | 1. First all modules in the array are registered with the `ModuleService`. 24 | 2. Then each module is activated 25 | 26 | This function takes an array of absolute module paths to load. 27 | 28 | ```javascript 29 | loadModules( [ 30 | "C:/path/to/module1", 31 | "C:/path/to/module2", 32 | "C:/path/to/module3" 33 | ] ); 34 | ``` 35 | 36 | You can easily drive this function with `directoryList()` like so: 37 | 38 | ```javascript 39 | loadModules( 40 | directoryList( path=resolvePath( 'modules/' ), type='dir' ) 41 | ); 42 | ``` 43 | -------------------------------------------------------------------------------- /task-runners/passing-parameters.md: -------------------------------------------------------------------------------- 1 | # Passing Parameters 2 | 3 | A task target can defined as many method arguments as it wants which can be passed in via command arguments when calling the task. 4 | 5 | **fun.cfc** 6 | 7 | ```javascript 8 | component{ 9 | function greet( string name, boolean verbose ){ 10 | print.line( 'Well, hello there #name#!' ); 11 | if( verbose ) { 12 | print.line( "You're looking quite well today." ); 13 | } 14 | } 15 | } 16 | ``` 17 | 18 | There's two ways to pass in the `name` and `verbose` parameters: positionally and via named parameters. 19 | 20 | ## Positional 21 | 22 | If you want to pass your parameters positionally, you **must include the task and target name**. 23 | 24 | ``` 25 | task run fun greet Brad false 26 | ``` 27 | 28 | ## Named 29 | 30 | A more self-documenting method is to use named parameters. Note, it is not necessary to pass the task and target name when using named parameters, but in this case, my example does not use the default task and target convention names, so I'll need to pass them anyway. Note that we start each parameter name with a colon (`:`) so they don't interfere with any of the parameters to the actual `task run` command. 31 | 32 | ``` 33 | task run taskFile=fun target=greet :name=Brad :verbose=false 34 | ``` 35 | 36 | The parameters `:name` and `:verbose` will be passed directly along to the task as `name` and `verbose`. 37 | 38 | ## Flags 39 | 40 | Tasks with boolean parameters can also have those passed using flags just like commands. Simply prepend a colon (`:`) to the name of the flag like so. 41 | 42 | ``` 43 | task run --no:verbose 44 | or 45 | task run --!:verbose 46 | ``` 47 | 48 | ## Mix it up 49 | 50 | Since `task run` is just a regular command, remember its parameters don't have to be hard coded. They can expressions or system settings, etc. 51 | 52 | ``` 53 | task run ${APIDocURL} ${APIDocPort:8080} 54 | task run taskFile=build :message=`cat message.txt` 55 | ``` 56 | -------------------------------------------------------------------------------- /task-runners/property-files.md: -------------------------------------------------------------------------------- 1 | # Property Files 2 | 3 | If you're touching Java, there's probably some property files in your future. We've included the `PropertyFile` module in CommandBox that you can call directly from CFML. There are also some commands so you can script the creation and updating of property files from the command line and CommandBox recipes. 4 | 5 | ## From the CLI 6 | 7 | ``` 8 | propertyFile show foo.properties 9 | propertyFile set propertyFilePath=foo.properties newProp=newValue 10 | propertyFile clear foo.properties newProp 11 | ``` 12 | 13 | ## From CFML 14 | 15 | ```javascript 16 | // Create and load property file object 17 | propertyFile( 'myFile.properties' ) 18 | .set( 'my.new.property', 'my value' ) 19 | .store(); 20 | 21 | // Get a property 22 | var value = propertyFile( 'myFile.properties' ) 23 | .get( 'existing.property' ); 24 | 25 | // Create one from scratch 26 | propertyFile() 27 | .set( 'brad', 'wood' ) 28 | .store( 'myFile.properties' ); 29 | ``` 30 | 31 | A `propertyFile` CFC instance can also be treated as a struct as it stores the properties in its `this` scope. 32 | 33 | ```javascript 34 | // Create object 35 | var propFile = propertyFile( 'myFile.properties' ); 36 | 37 | // Access proeprties 38 | print.line( propFile.brad ); 39 | 40 | // Change/add properties 41 | propFile.foobar = true; 42 | propFile[ 'another.new.property' ] = false; 43 | 44 | // Save it 45 | propFile.store(); 46 | ``` 47 | -------------------------------------------------------------------------------- /task-runners/sending-e-mail.md: -------------------------------------------------------------------------------- 1 | # Sending E-mail 2 | 3 | To send email, use `cfmail` tag making sure you set `async=false` (see below). Not setting this flag to `false` may result in undelivered email because mail may still exist in Lucee spooler (Lucee tasks) when your task runner exits. 4 | 5 | ```javascript 6 | mail 7 | subject=subject 8 | from=from 9 | to=to 10 | cc=cc 11 | bcc=bcc 12 | replyTo=replyTo 13 | type=type 14 | server=server 15 | port=port 16 | username=username 17 | password=password 18 | useTls=tls 19 | usessl=ssl 20 | async=false { 21 | writeOutput(emailBody); 22 | }; 23 | ``` 24 | 25 | ### Connecting to SMTP Services Using SSL or TLS 26 | 27 | If you cannot connect to a SMTP server that requires `SSL` or `TLS`, like [Amazon SES](https://aws.amazon.com/ses/), one workaround is to install a local SMTP server and configure it as a relay to your SMTP server. This has been done successfully on Windows servers using [hMailServer](https://www.hmailserver.com/) (free, opensource), which is fairly easy to install and configure as an SMTP relay. 28 | -------------------------------------------------------------------------------- /task-runners/shell-integration.md: -------------------------------------------------------------------------------- 1 | # Shell Integration 2 | 3 | Your task might need to get information about its environment or perhaps proxy to other commands. Here is a handful of useful methods available to all commands. 4 | 5 | ## getCWD() 6 | 7 | This method will return the Current Working Directory that the user has changed to via the `cd` command. The path will be expanded and fully qualified. 8 | 9 | ## shell.clearScreen() 10 | 11 | This method on the shell object will clear all text off the screen and redraw the CommandBox prompt. 12 | 13 | ## shell.getTermWidth() 14 | 15 | This shell method returns the number of characters wide that the terminal is. Can be useful for outputting long lines and making sure they won't wrap. 16 | 17 | ## shell.getTermHeight() 18 | 19 | This shell method returns the number of characters tall the terminal is. Can be useful for [outputting ASCII art](https://github.com/bdw429s/CommandBox-Image-To-ASCII). 20 | -------------------------------------------------------------------------------- /task-runners/task-output/printing-columns.md: -------------------------------------------------------------------------------- 1 | # Printing Columns 2 | 3 | If you have a large list of items you need to output, you can use the `print.columns()` helper. Pass an array of simple values to be printed, and columns will be created on the screen based on the widest item and the terminal width. 4 | 5 | ```javascript 6 | print.columns( directoryList( resolvePath( /lib ) ) ) 7 | ``` 8 | 9 | You can also pass a UDF as the second argument which will be called for each item in the array and can return a string with additional formatting text for the print helper to format that item. The closure receives the following arguments: 10 | 11 | * item (string) being printed 12 | * row number 13 | * column number 14 | 15 | ``` 16 | print.columns( 17 | directoryList( resolvePath( /lib ) ), 18 | (item,row,col)=>item.endsWith('.txt') ? 'blue' : 'green' 19 | ) 20 | ``` 21 | 22 | This example would print out a list of files in the directory, coloring all text files blue, and the rest green. 23 | 24 | This helper is the same as the `printColumns` command with the differences being the command accepts no formatting closure and will convert list data into an array or will accept a JSON array directly. 25 | 26 | ``` 27 | printColumns data="1,2,3,4,5" delimiter="," 28 | 29 | # or ... 30 | ls --simple | printColumns 31 | ``` 32 | -------------------------------------------------------------------------------- /task-runners/task-target-dependencies.md: -------------------------------------------------------------------------------- 1 | # Task Target Dependencies 2 | 3 | For a task that has more than one target (method) you can specify dependencies that will run, in the order specified, prior to your final target. Specify task target dependencies as a comma-delimited list in a `depends` annotation on the target function itself. There is no limit to how many target dependencies you can have, nor how deep they can nest. 4 | 5 | ```javascript 6 | component { 7 | 8 | function run() depends="runMeFirst" { 9 | } 10 | 11 | function runMeFirst() { 12 | } 13 | 14 | } 15 | ``` 16 | 17 | Given the above Task Runner, typing 18 | 19 | ```bash 20 | task run 21 | ``` 22 | 23 | would run the `runMeFirst()` and `run()` method in that order. 24 | 25 | Any parameters passed to the target will also be passed along to methods who are dependencies. Don't forget, task CFCs are re-created every time they are executed as transients, so feel free to borrow the `variables` scope inside the CFC to share state between methods. 26 | -------------------------------------------------------------------------------- /task-runners/threading-async.md: -------------------------------------------------------------------------------- 1 | # Threading/Async 2 | 3 | The CommandBox CLI is implemented as a single long request in the underlying Lucee server. Due to this it is required to make a unique thread name every call to the task or else an error can occur. The following is an example you can use for running threads. 4 | 5 | ```javascript 6 | var threadName = createGUID(); 7 | cfthread( action="run" name=threadName) { 8 | //Thread body 9 | } 10 | cfthread( action="terminate" name=threadName); 11 | ``` 12 | 13 | ## AsyncManager 14 | 15 | CommandBox bundles WireBox and therefore has access to the `AsyncManager` library that ColdBox MVC has. It can be used to create async code and even scheduled tasks. CommandBox uses the AsyncManager internally for timed screen redraws. 16 | 17 | You can access the `AsyncManager` class in the variables scope or call the `async()` method of any Task Runner or custom command. 18 | 19 | ```javascript 20 | // Parallel Executions 21 | async().all( 22 | () => hyper.post( "/somewhere" ), 23 | () => hyper.post( "/somewhereElse" ), 24 | () => hyper.post( "/another" ) 25 | ).then( (results)=> logResults( results ) ); 26 | ``` 27 | 28 | You can find the full documentation here: 29 | 30 | {% embed url="https://coldbox.ortusbooks.com/digging-deeper/promises-async-programming" %} 31 | 32 | And the API docs here: 33 | 34 | {% embed url="https://apidocs.ortussolutions.com/coldbox/current/index.html?coldbox/system/async/AsyncManager.html" %} 35 | 36 | -------------------------------------------------------------------------------- /task-runners/using-parameters.md: -------------------------------------------------------------------------------- 1 | # Using Parameters 2 | 3 | Regardless of whether your task is called with named parameters, positional parameters or boolean flags, you'll access them the same way: via the standard CFML arguments scope. An exception will be thrown if required parameters are not passed, and the defaults you configured will also work just like you expect. 4 | 5 | If the parameters were escaped when typed into the command line, you will receive the final unescaped version in your task. 6 | 7 | ## Dynamic Parameters 8 | 9 | Users can pass named or positional parameters that aren't declared, and they will come through the `arguments` scope. Named parameters will be accessable as `arguments.name`, and positional parameters as `arguments[ 1 ]`, `arguments.[ 2 ]`, etc. 10 | 11 | ```bash 12 | task run :foo=bar :baz=bum 13 | ``` 14 | 15 | ## File System Paths As Parameters 16 | 17 | If your task accepts a file or folder path from the user, you'll want to resolve that path before you use it. To do this, use the `fileSystemUtil` object that is available to all tasks via the BaseTask class. The method `resolvePath()` will make the file system path canonical and absolute. This ensures you have a fully qualified path to work with even if a user might passed a folder relative to their current working directory passed something like `../../`. 18 | 19 | ```javascript 20 | component { 21 | 22 | function run( String directory ) { 23 | // This will make each directory canonical and absolute 24 | directory = fileSystemUtil.resolvePath( directory ); 25 | print.line( directory ); 26 | } 27 | } 28 | ``` 29 | 30 | If you run that task and pass a full file path such as `C:\sandbox\testSite`, you would get that exact same path back as the output. 31 | 32 | However, if you changed the interactive shell to the `C:\sandbox` directory and then ran the task with `testsite` as the input, the relative path would now still resolve to `C:\sandbox\testSite`. 33 | 34 | If, from the same directory, you passed `testsite/foo/bar/../../`, you would still get `C:\sandbox\testSite` as the path. 35 | -------------------------------------------------------------------------------- /testbox-integration/README.md: -------------------------------------------------------------------------------- 1 | # TestBox Integration 2 | 3 | TestBox is a next generation testing framework for ColdFusion (CFML) that is based on BDD (Behavior Driven Development) for providing a clean obvious syntax for writing tests. It contains not only a testing framework, runner, assertions and expectations library but also ships with MockBox, A Mocking & Stubbing Framework. It also supports xUnit style of testing and MXUnit compatibilities. 4 | 5 | [https://www.ortussolutions.com/products/testbox](https://www.ortussolutions.com/products/testbox) 6 | 7 | ## CLI Commands 8 | 9 | We have a number of TestBox commands built into CommandBox to make your life easier. Check them out by requesting `help` on the `testbox` command namespace. 10 | 11 | ``` 12 | testbox help 13 | ``` 14 | -------------------------------------------------------------------------------- /testbox-integration/test-watcher.md: -------------------------------------------------------------------------------- 1 | # Test Watcher 2 | 3 | This is an extension of the `testbox run` command but will watch the files in a directory and run the default TestBox suite on any file change. 4 | 5 | ``` 6 | testbox watch 7 | ``` 8 | 9 | In order for this command to work, you need to have started your server and configured the URL to the test runner in your `box.json`. 10 | 11 | ``` 12 | package set testbox.runner=http://localhost:8080/tests/runner.cfm 13 | server start 14 | testbox watch 15 | ``` 16 | 17 | You can also control what files to watch. 18 | 19 | ``` 20 | testbox watch **.cfc 21 | ``` 22 | 23 | If you need more control over what tests run and their output, you can set additional options in your `box.json` which will be picked up automatically by `testbox run` when it fires. 24 | 25 | ``` 26 | package set testbox.verbose=false 27 | package set testbox.labels=foo 28 | package set testbox.testSuites=bar 29 | package set testbox.watchDelay=1000 30 | package set testbox.watchPaths=/models/**.cfc 31 | ``` 32 | 33 | This command will run in the foreground until you stop it. When you are ready to shut down the watcher, press `Ctrl+C`. 34 | -------------------------------------------------------------------------------- /usage/256-color-support.md: -------------------------------------------------------------------------------- 1 | # 256 Color Support 2 | 3 | CommandBox has support for 256 colors in the console, but this is limited by the terminal in use. For instance, SSHing into a Linux server with PutTTY only supports 8 colors. Windows cmd only supports 16 colors. Most Mac terminals seem to support 256 colors by default. 4 | 5 | For Windows users, we recommend using an add-on terminal like ConEMU which has good 256 color support out of the box. To find out how many colors your terminal supports, you can run this command: 6 | 7 | ``` 8 | system-colors 9 | ``` 10 | 11 | ![256 Color support from ConEMU in Windows](<../.gitbook/assets/image (15) (1).png>) 12 | 13 | This will show you at the top how many colors are supported. It will also output a sample of each of the 256 colors. Terminals that support less than 256 colors will "round" down and show the next closest color automatically. Some darker colors might turn to black. Note, some advanced terminals allow the user to choose color themes which will also change the default colors. CommandBox has no control over how colors show up for you. 14 | 15 | ## Color Names 16 | 17 | The names and numbers of each color are unique and important if you want to do any Task Runners, custom commands that make use of these colors. Modules like Bullet Train also allow you to customize their colors. You can specify a color by its name like `LightGoldenrod5` or its number (`221`). 18 | 19 | In a Task Runner or custom command, the print helper would look like this: 20 | 21 | ``` 22 | print.lightGoldenrod5Line( 'This is pretty' ); 23 | print.color221( 'This is the same color as above' ); 24 | ``` 25 | 26 | Here's an example of customizing your Bullet Train module to use fancy colors. (Color 21 is `Blue1`) 27 | 28 | ``` 29 | config set modules.commandbox-bullet-train.packageBG=lightGoldenrod5 30 | config set modules.commandbox-bullet-train.packageText=color21 31 | ``` 32 | -------------------------------------------------------------------------------- /usage/a-little-fun.md: -------------------------------------------------------------------------------- 1 | # A Little Fun 2 | 3 | We believe all work and no play makes you a dull boy (or girl!). You'll notice the interactive shell has a handful of quotes and tips that show up when the shell starts. If you have ideas or suggestions for new ones, please send pull requests or let us know. 4 | 5 | ## ASCII Art Stereograms 6 | 7 | If you remember the "_Magic Eye"_ books from your childhood, you'll be pleased to know CommandBox has an ASCII Art Stereogram for every day of the month. You'll find it hiding inside the `info` command. The image will change every day at midnight. 8 | 9 | ``` 10 | _( ) _( ) _( ) _( ) _( ) 11 | _( ) )_ _( ) )_ _( ) )_ _( ) )_ _( ) )_ 12 | (____(___) (____(___) (____(___) (____(___) (____(___) 13 | 14 | 15 | /\ /\ /\ /\ /\ 16 | / \ /\ / \ /\ / \ /\ / \ /\ / \ /\ 17 | / \/ \ / \/ \ / \/ \ / \/ \ / \/ \ 18 | \/ \ / \/ / \/ 19 | .. .. .. .. .. .. 20 | " " " " " " " 21 | * * * * * * * * 22 | @ @ @ @ @ @ @ @ @ @ 23 | \|/ \|/ \|/ \|/ \|/ \|/ \|/ \|/ \|/ \|/ 24 | ``` 25 | 26 | If you're not familiar with how to view these, you want to "diverge" your eyes. This is what happens when you look at something far away and it's the opposite of crossing your eyes. Start with your face closer to the monitor and looking square on. Relax your vision and look past the monitor until the image starts to overlap itself (that's your eyes diverging) until the repeated elements match up again (like the clouds above). Different parts of the image will appear to be different distances away from you. 27 | 28 | If you can't see it right away, don't worry. Practice makes perfect and the more you do it, the easier it is. You'll get the hang of it, we promise! 29 | -------------------------------------------------------------------------------- /usage/ad-hoc-command-aliases.md: -------------------------------------------------------------------------------- 1 | # Ad-hoc Command Aliases 2 | 3 | Do you ever get tired of typing some built in commands and you'd like to just alias them as something simpler? You can create arbitrary alises now that reduce the amount of typing you do. 4 | 5 | ``` 6 | config set command.aliases.cca="coldbox create app" 7 | cca myApp 8 | ``` 9 | 10 | In the above example, it's the same thing as typing `coldbox create app myApp`. 11 | 12 | Aliases are treated as in-place shell expansions so you can alias anything including default parameters as well as multiple commands chained together. 13 | 14 | ``` 15 | config set command.aliases.foobar="echo brad | grep brad | sed s/rad/foo/ > foo.txt && cat foo.txt" 16 | foobar 17 | ``` 18 | 19 | In the above example, typing `foobar` is the same as running the giant command string that's being set into the alias. 20 | 21 | If you create an alias that matches an existing command name, your alias will take precedence since aliases are expanded before commands are resolved. 22 | 23 | Here we can change the name of a common command like `echo` that we really wish had been named `print`. 24 | 25 | ``` 26 | config set command.aliases.print=echo 27 | print brad 28 | ``` 29 | 30 | Let's take it a step further and alias the alias! 31 | 32 | ``` 33 | config set command.aliases.cout=print 34 | cout brad 35 | ``` 36 | 37 | Running `cout brad` is the same as running `print brad` which is the same as running `echo brad`. Try not to get dizzy when doing this, please. 38 | -------------------------------------------------------------------------------- /usage/auto-update-checks.md: -------------------------------------------------------------------------------- 1 | # Auto Update Checks 2 | 3 | Never miss an update again by installing the CommandBox update check module for ForgeBox. It will check for new versions of the core CommandBox CLI as well as any of your installed system modules once a day when the CLI starts up in interactive mode. Internet connection required. 4 | 5 | {% embed url="https://www.forgebox.io/view/commandbox-update-check" %} 6 | CommandBox Update Check Module 7 | {% endembed %} 8 | -------------------------------------------------------------------------------- /usage/command-help.md: -------------------------------------------------------------------------------- 1 | # Command Help 2 | 3 | Help is integrated at every level in CommandBox. You can help global help, namespace help, or command help at any time. 4 | 5 | ## Global Help 6 | 7 | To get an overall list of all the commands you have available to run, simply type `help` at the shell. 8 | 9 | ![Global Help](../.gitbook/assets/global_help.png) 10 | 11 | ## Namespace Help 12 | 13 | Next, drill down and get help on a specific namespace like `server`. 14 | 15 | ![Namespace Help](../.gitbook/assets/namespace_help.png) 16 | 17 | ## Command Help 18 | 19 | And finally, get help on a single command such as `server stop`. We can see the command is also aliased as just `stop` as well as all the possible parameters and their types along with a few sample ways to call the command. 20 | 21 | ![Command Help](../.gitbook/assets/command_help.png) 22 | 23 | ## HTML Command API Docs 24 | 25 | For a full list of all the commands that ship with CommandBox as well as all their paramaters and samples, please visit our [Command API docs](http://apidocs.ortussolutions.com/commandbox/current) which are auto-generated each build. This is the same information available to you via the `help` command, but in a searchable format you can browse outside of the CLI. 26 | 27 | * [http://apidocs.ortussolutions.com/commandbox/current](http://apidocs.ortussolutions.com/commandbox/current) 28 | 29 | ## System Logs 30 | 31 | Sometimes, you need to view the CommandBox log file. Maybe it is to debug a command you are writing or to [submit a crash report](https://ortussolutions.atlassian.net/secure/RapidBoard.jspa?rapidView=24\&projectKey=COMMANDBOX). The `system-log` command outputs the path to the CommandBox log file. You can use it creatively by piping its output in to other commands: 32 | 33 | ```bash 34 | CommandBox> system-log | open 35 | CommandBox> system-log | cat 36 | CommandBox> system-log | tail 37 | ``` 38 | -------------------------------------------------------------------------------- /usage/default-command-parameters.md: -------------------------------------------------------------------------------- 1 | # Default Command Parameters 2 | 3 | Do you also always type certain parameters every time you run a command, like always typing `--force` after `rm`? Any command parameter can be defaulted at a global level so you don't have to type it every time. These defaults will always be overridden if you actually supply the parameter when running the command. 4 | 5 | ``` 6 | config set command.defaults.rm.force=true 7 | rm myFile.txt 8 | ``` 9 | 10 | The above example is the same as running `rm myFile.txt --force` since we've defaulted the `force` parameter to always be true when not otherwise specified. If you wanted to override your default, you could do so by actually specifying the parameter from the CLI like this: 11 | 12 | ``` 13 | rm myFile.txt --NoForce 14 | ``` 15 | -------------------------------------------------------------------------------- /usage/execution/cfml-files/README.md: -------------------------------------------------------------------------------- 1 | # CFML Files 2 | 3 | CommandBox's true power comes from it's command-based architecture, but we also support just running plain-jane .cfm files as well. 4 | 5 | ## Running plain CFML files 6 | 7 | Take the following file for example: 8 | 9 | **test.cfm** 10 | 11 | ```markup 12 | #now()# 13 | ``` 14 | 15 | We can execute this file directly from our native OS prompt by simply passing the filename straight into the box binary. 16 | 17 | ```bash 18 | C:\> box test.cfm 19 | {ts '2015-02-19 20:14:13'} 20 | ``` 21 | 22 | Or, I can run it from within the CommandBox interactive shell using the execute command: 23 | 24 | ```bash 25 | CommandBox> execute test.cfm 26 | {ts '2015-02-19 20:12:41'} 27 | ``` 28 | 29 | ## #! Goodness 30 | 31 | Now, you people on Unix-based operating systems like Mac and Linux get a special treat. You can actually create natively executable shell scripts that contain CFML! Check out this file that has the special hash bang at top: 32 | 33 | **test** 34 | 35 | ```bash 36 | #!/usr/bin/env box 37 | 38 | #now()# 39 | ``` 40 | 41 | All we need to do is make it executable 42 | 43 | ```bash 44 | chmod +x test 45 | ``` 46 | 47 | And then just run it like any other shell script! 48 | 49 | ```bash 50 | $> ./test 51 | 52 | {ts '2015-02-19 20:31:32'} 53 | ``` 54 | 55 | ## CFML Engine 56 | 57 | The underlying engine used to execute your files will be the version of Lucee Server that the CLI is currently running on. Note, this can change between releases, and you can see the current version by running the `info` command. If you want to try to use the `` tag to do things like create datasources, the default password for the Lucee server context is `commandbox`. 58 | 59 | Hopefully this gives you a lot of ideas of how to start using CFML on your next automation task. And if you want even more control like print objects, object oriented code, and fancy parameters, look into making custom [CommandBox commands](../../../developing-for-commandbox/commands/). 60 | -------------------------------------------------------------------------------- /usage/interactive-shell-features.md: -------------------------------------------------------------------------------- 1 | # Interactive Shell Features 2 | 3 | When you run `box` without any parameters, you get the CommandBox interactive shell. We use a library called JLine for this interaction and it has a number of bash-like behaviors to make you more productive. CommandBox also bundles several bash-like commands to give you a consistent shell regardless of whether you're on Windows or Linux. 4 | 5 | ## Ctrl-C & Ctrl-D 6 | 7 | Pressing Ctrl-C will send an interrupt signal to the terminal which will end any currently executing command and exit you back to the shell's prompt. Pressing Ctrl-C if you're already at the prompt won't do anything at all. 8 | 9 | Pressing Ctrl-D from a prompt sends an OEF signal and will exit out of the shell entirely, just like if you had run the `exit` command. 10 | 11 | ## History Search 12 | 13 | CommandBox allows you to re-run items from your command and/or REPL history by pressing the up arrow to cycle through previous commands. You can type a partial command like `cd` and then hit up arrow and the history items will be filtered to items starting with that. You can also use what's commonly known as `i-search`. Press Ctrl-Shift-R to open a search from the console where you can search your entire command history by keyword. Keep pressing Ctrl-Shift-R to cycle through the results. Press Ctrl-Shift-S to cycle backwards through the results. 14 | 15 | ## Change to Previous Directory 16 | 17 | Like Powershell or Bash, you can type the following to switch back to the previous working directory: 18 | 19 | ```bash 20 | cd - 21 | ``` 22 | 23 | If you run this same command more than once, you will keep toggling between the same two directories (bash behavior) 24 | -------------------------------------------------------------------------------- /usage/parameters/globbing-patterns.md: -------------------------------------------------------------------------------- 1 | # Globbing Patterns 2 | 3 | When a command has an argument with a type of `Globber` for a file path, that means you can use file globbing patterns to affect more than one file at a time. Globbing patterns are common in Bash as well as places like your `.gitignore` file. They use common wildcard patterns to provide a partial path that can match zero or hundreds of files all at the same time. 4 | 5 | ## "?" matches a single character 6 | 7 | If a globbing pattern contains a question mark, that will match any single character. So a pattern of `ca?.txt` would match `car.txt`, and `cat.txt`, but not `cart.txt`. You can use a wildcard more than once. `p?p?.cf?` would match files named `papa.cfm` and `pipe.cfc`. 8 | 9 | ## "\*" matches any number of characters within name 10 | 11 | If a globbing pattern contains a single asterisks, that will match zero or more characters inside a filename or folder name. So `d*o` matches `doodoo`, `dao`, and just `do`. The wildcard only counts _inside_ a file or folder name, so `models/*.cfc` will only match cfc files in the root of the models folder. 12 | 13 | ## "\*\*" matches any number of characters across all directories 14 | 15 | To extend the previous example, if we did `models/**.cfc` that would match any cfc file in _any_ subdirectory, no matter how deep. 16 | 17 | ## Globbing examples 18 | 19 | Here's some examples of what file globbing might look like: 20 | 21 | ``` 22 | CommandBox> rm temp*.txt 23 | CommandBox> cp *.cfm backup/ 24 | CommandBox> touch build/*.properties 25 | ``` 26 | 27 | Here's some more examples of how the wildcards work 28 | 29 | ``` 30 | // Match any file or folder starting with "foo" 31 | foo* 32 | 33 | // Match any file or folder starting with "foo" and ending with .txt 34 | foo*.txt 35 | 36 | // Match any file or folder ending with "foo" 37 | *foo 38 | 39 | // Match a/b/z but not a/b/c/z 40 | a/*/z 41 | 42 | // Match a/z and a/b/z and a/b/c/z 43 | a/**/z 44 | 45 | // Matches hat but not ham or h/t 46 | /h?t 47 | ``` 48 | 49 | Since the Globber library can handle more than one globbing pattern, any command that uses a Globber type can accept a comma-delimited list of patterns. The following will list any .cfm AND .md files in the directory. 50 | 51 | ```bash 52 | dir *.cfm,*.md 53 | ``` 54 | -------------------------------------------------------------------------------- /usage/parameters/piping-into-commands.md: -------------------------------------------------------------------------------- 1 | # Piping into Commands 2 | 3 | The CommandBox interactive shell already allows for a command to pipe data into another Command. 4 | 5 | ```bash 6 | cat myfile.txt | grep "find me" 7 | ``` 8 | 9 | Since CommandBox commands don't have a "standard input", the output of the previous command is passed into the second command as its first parameter. In this instance, the `grep` command's first parameter is called `input` so it receives the value returned by the `cat` command. The `"find me"` text becomes the second parameter-- in this case, `expression`. 10 | 11 | ## Examples 12 | 13 | There is nothing special about a parameter that can received piped input. In fact, any command can receive piped input for its first parameter. The following commands all accomplish the same thing. 14 | 15 | ```bash 16 | coldbox create app "My App" 17 | ``` 18 | 19 | ```bash 20 | echo "My App" | coldbox create app 21 | ``` 22 | 23 | ```bash 24 | echo "My App" > appName.txt 25 | cat appName.txt | coldbox create app 26 | ``` 27 | 28 | This allows you to get creative by combining commands together like so: 29 | 30 | ```bash 31 | package set name="hello world" 32 | package show name | sed s/hello/goodbye/ 33 | ``` 34 | 35 | This takes a package name and replaces some text on output. One benefit is that Windows users don't have a native `sed` command in their OS, but those commands inside a CommandBox Recipe will execute consistently on any machine. 36 | 37 | ## Piping From The OS 38 | 39 | What if you aren't using the interactive shell and you want to pipe into CommandBox from your OS's native shell? This is also supported, and as long as there is a command specified, the piped input will become the first parameter as before. 40 | 41 | ```bash 42 | C:\> echo coldbox | box install 43 | C:\> echo reverse('this is a test') | box repl 44 | ``` 45 | 46 | If you pipe text directly into the box executable with no command specified in the parameters, each line of your piped text will be read from the standard input as a command. 47 | 48 | ```bash 49 | C:\> echo version | box 50 | C:\> box < commands.txt 51 | ``` 52 | -------------------------------------------------------------------------------- /usage/sql-command.md: -------------------------------------------------------------------------------- 1 | # sql Command 2 | 3 | There is a `sql` command which will accept any sort of data as JSON, marshal it into a query object and allow you to alias, filter, order, and limit the rows on the fly using CFML's query of queries. 4 | 5 | ## Parameters 6 | 7 | * `data` - The JSON to process 8 | * `select` - A SQL list of column names, eg. "name,version" 9 | * `where` - A SQL where filter used in a query of queries, eg. "name like '%My%'" 10 | * `orderby` - A SQL order by used in a query of queries, eg. "name asc, version desc" 11 | * `limit` - A SQL limit/offset used in a query of queries, eg. "5" or "5,10" (eg. offset 5 limit 10) 12 | * `headerNames` - An list of column headers to use (used for array of arrays) 13 | 14 | When using an array of arrays and not specifying `headerNames`, the columns will be named `col_1`, `col_2`, `col_3`, etc... 15 | 16 | ## Examples 17 | 18 | Filter, sort, limit, and select extensions installed into the CLI (output as table) 19 | 20 | ```bash 21 | #extensionlist | sql select=id,name where="name like '%sql%'" orderby=name limit=3 | printTable 22 | ``` 23 | 24 | Order and select JSON data from a file (output as JSON) 25 | 26 | ```bash 27 | cat myfile.json | sql select=col1,col2 orderby=col2 28 | ``` 29 | 30 | Limit JSON (output as table) 31 | 32 | ```bash 33 | sql data=[{a:1,b:2},{a:3,b:4},{a:5,b:6}] where="a > 1" | printTable 34 | ``` 35 | 36 | The `sql` command works very nicely with the `tablePrinter` command. 37 | --------------------------------------------------------------------------------