forge-cli-utils

Command line tools for Autodesk Forge services.

Installation

Using npm

Install the forge-cli-utils library, either in your own npm project (npm install --save forge-cli-utils), or globally (npm install --global forge-cli-utils).

Self-contained binaries

Scripts in this library are also packaged into self-contained binaries for various platforms using the pkg module. You can download the binaries from release pages.

Usage

Providing Forge credentials

The CLI tools require Forge app credentials to be provided as env. variables.

If you don't have a Forge app yet, check out this tutorial: https://forge.autodesk.com/en/docs/oauth/v2/tutorials/create-app/.

On macOS and linux:

export FORGE_CLIENT_ID=<your client id>
export FORGE_CLIENT_SECRET=<your client secret>

On Windows, using cmd.exe:

set FORGE_CLIENT_ID=<your client id>
set FORGE_CLIENT_SECRET=<your client secret>

On Windows, using PowerShell:

$env:FORGE_CLIENT_ID = "<your client id>"
$env:FORGE_CLIENT_SECRET = "<your client secret>"

Scripts

Use the following scripts for different Forge services:

• forge-dm - Forge Data Management service
• forge-md - Forge Model Derivative service
• forge-da - Forge Design Automation service

Each script expects a subcommand similar to git. To get a list of all available commands, run the script with -h or --help.

When using bash, use the tools/autocomplete-bash.sh script to setup a simple auto-completion for the basic commands of each script: source tools/autocomplete-bash.sh.

Most commands output raw JSON output from Forge services by default, but in many cases you can use -s or --short flag to output a more concise version of the results. The raw JSON output can also be combined with tools like jq to extract just the pieces of information that you need:

# Listing buckets as full JSON
forge-dm list-buckets

# Listing bucket keys
forge-dm list-buckets --short

# List creation dates of all buckets
forge-dm list-buckets | jq '.[] | .createdDate'

Examples

Data Management

# Listing buckets as full JSON
forge-dm list-buckets

# Listing object IDs of specific bucket
forge-dm list-objects my-test-bucket --short

# Listing object IDs without specifying a bucket (will show an interactive prompt with list of buckets to choose from)
forge-dm list-objects --short

# Getting an URN of an object
forge-dm object-urn my-bucket-key my-object-key

Design Automation

# Creating a new app bundle
forge-da create-appbundle BundleName path/to/bundle/zipfile Autodesk.Inventor+23 "Bundle description here."

# Updating existing activity
forge-da update-activity ActivityName BundleName BundleAlias Autodesk.Inventor+23 --input PartFile --output Thumbnail --output-local-name thumbnail.bmp

# Creating work item
forge-da create-workitem ActivityName ActivityAlias --input PartFile --input-url https://some.url --output Thumbnail --output-url https://another.url --short

When specifying inputs and outputs for an activity or work item, --input-* and --output-* arguments are always applied to the last input/output ID. For example, consider the following sequence of arguments: --input InputA --input-local-name house.rvt --input InputB --input InputC --input-url https://foobar.com. Such a sequence will define three inputs: InputA with local name house.rvt, InputB (with no additional properties), and InputC with URL https://foobar.com. For more details, see https://github.com/petrbroz/forge-cli-utils/wiki/Design-Automation-Inputs-and-Outputs

Model Derivative

# Translating a model based on its URN
forge-md translate dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6cG9jLWJvdXlndWVzLWltbW9iaWxpZXIvaW5wdXQucnZ0

# Showing an interactive prompt with all viewables in an URN, and then getting properties of the selected viewable
forge-md get-viewable-props dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6cG9jLWJvdXlndWVzLWltbW9iaWxpZXIvaW5wdXQucnZ0

# Download the derivatives once translation is completed, -u --guid <GUIDs of derivatives to download, optional, separated by comma>, -c --directory <path to save derivatives, optional>
forge-md download-derivatives dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6cG9jLWJvdXlndWVzLWltbW9iaWxpZXIvaW5wdXQucnZ0 -c '/path/to/output/optional' -u 'cdcf63c6-6a67-ffd2-2a8e-1e31397052f7'

For additional examples, check out the examples subfolder.

Additional Resources

• blog post on auto-deploying Design Automation plugins from Visual Studio: https://forge.autodesk.com/blog/deploying-design-automation-visual-studio