Command line

Last updated July 11, 2025

Cloudpack is meant to be run as a CLI. After installing @ms-cloudpack/cli you can run it as follows:

txt

cloudpack <command> [options]

The most commonly-used commands are init and start.

To see all available commands:

txt

cloudpack --help

To view a command's help, including the latest list of options (these do the same thing):

txt

cloudpack help <command>
cloudpack <command> --help

Common options

These options work with most sub-commands.

txt

Common options:
  --cache-path <path>           Custom cache folder. To change the default, run
                                  `cloudpack config set cachePath <path>`.
  -c, --config <filename>       Custom config file name to use instead of
                                  cloudpack.config.json.
  --define <key=value>          Define a global variable. Can be specified
                                  multiple times.
  --features <featureNames...>  Enable experimental features.

Logging options:
  -v, --verbose                 Show additional details in logging.
  -d, --debug                   Show debug information (superset of --verbose).
  -q, --quiet                   Disable non-essential logging.
  -n, --no-color                Disable colors in the output.
  --log-file                    Write a log file with all console output.

These work with either the top-level cloudpack command or any sub-command:

txt

-h, --help       display help for command
-V, --version    output the version number

`init`

Validate an app's compatibility with Cloudpack, and generate any necessary configuration overrides (cloudpack.generated.json).

If the current folder has a cloudpack.config.json, init will run against only that folder. Otherwise, it will run against all folders with a cloudpack.config.json (or only the ones matching --app).

Usage: cloudpack init [options]

init workflow details

Troubleshooting cloudpack init

Options

txt

--reset                 Ignore the previous generated config.
--check                 Fail if updates to the generated config are required.
--match <match...>      Only evaluate specific package(s), optionally with a version:
                          e.g. "foo", "@foo/*", "foo@1.2.3"
--app <appPackageName>  Run Cloudpack targeting a specific app.
--no-cache              Rebuild all packages, rather than using cached assets.
--log-resolve-map       Log the resolve map to "resolve-map.json".
--log-bundle-info       Write log files in each package's output folder with
                          bundle input, output, and info. (Requires --no-cache
                          if bundle output already exists.)

`start`

Starts the Cloudpack web inner-loop for an app.

If the --app option is specified, it will start that app (preferring a specific name match, or falling back to substrings).
If the current package folder has a Cloudpack config, it will start that app.
Otherwise, it will scan for packages with Cloudpack configs and show a menu in the CLI.
If no Cloudpack configs are found, it will attempt to start the current package as an app with default settings.

Usage: cloudpack start [options]

start workflow details

Troubleshooting cloudpack start

Options

Common options also apply.

txt

--app <packageName>         Run Cloudpack targeting a specific app.
--open [url]                Open the browser (to the URL if provided).
--no-open                   Do not open the browser.
--no-cache                  Rebuild all packages, rather than using cached assets.
--mode <mode>               The mode to run the app in:
                              "library" (default) or "production".
--show-overlay <when>       Override whether to show the Cloudpack overlay
                              (status badge and dialog) in the app UI:
                              "always" (default), "errors-only", "never"
--api-server-port <port>    Port for the API server (single, comma-separated,
                              or range with dash).
--app-server-port <port>    Port for the app server (as above).
--bundle-server-port <port> Port for the bundle server (as above).
--login <method>            How to authenticate against the remote cache
                              (only if starting a remote app).
                              Default: "azure-cli" in CI, "device-code" in
                              Github Codespaces, "interactive" otherwise
--log-resolve-map           Log the resolve map to "resolve-map.json".
--log-bundle-info           Write log files in each package's output folder with
                              bundle input, output, and info. (Requires
                              --no-cache if bundle output already exists.)

Examples

Starting with --define flags:

cloudpack start --define FEATURE_FLAGS.enableNewUI=true
cloudpack start --define API_URL=https://api.example.com,DEBUG=true,API_PORTS=[8000,8001]

Values without quotes will be automatically converted to appropriate types:

true and false become boolean values
Numbers become numeric values
Arrays are converted to arrays
Everything else remains as strings

These define flags will be handled the same way as those specified in the define section of the configuration file, but take precedence over values in the config file.

`link`

Link the package(s) found within the current folder to an existing cloudpack start session.

Usage: cloudpack link [options]

link workflow details

Troubleshooting cloudpack link

Options

Common options also apply.

txt

  --remote [remote]     Link to a remote session. Specify one of the following,
                          listed in order of preference:
                          - WebSocket URL: e.g., "wss://example.com:9890"
                              or "ws://example.com:9890"
                          - URL: e.g., "https://example.com" or "https://example.com"
                          - hostname: e.g., "example.com"
                              (attempts both wss:// and ws:// connections)
                          - no value: Uses "localhost"
                              (attempts both wss:// and ws:// connections)
--ignore [packages...]  Ignore the given packages when linking. Can be used to
                          ignore packages in the current repo that have issues
                          being bundled.
--all                   Link all internal packages discovered within the linked
                          repo's graph.
--ignore-resolutions    Don't apply resolutions from the host repo's package.json
                          to linked packages.
--resolve-strategy <strategy>
                        Strategy to use when resolving linked packages.
                          - "dedupe" (default): Attempt to dedupe packages from
                            the resolve map by removing all but the highest
                            version that satisfies semver requirements from all
                            parent entries.
                          - "duplicate": Allow duplicates (don't bump dependencies).
--log-resolve-map       Log the resolve map to "resolve-map.json".

`unlink`

Unlinks the package(s) found within the current folder from a cloudpack start session.

Options

Common options also apply.

txt

--log-resolve-map     Log the resolve map to "resolve-map.json" for diagnostics.

`bundle`

Bundle one or more packages. It will bundle the current package unless --match is specified.

Usage: cloudpack bundle [options]

Options

Common options also apply.

txt

--match <match...>      Bundle specific package(s), optionally with a version:
                          e.g. "foo", "@foo/*", "foo@1.2.3"
--mode <mode>           The mode to bundle the package in. (library | production)
                          (default: "library")
--bundler <name>        Force using a specific bundler.
                          (choices: "ori", "rollup", "rspack", "webpack")
--outdir <path>         Path for the bundle output, relative to current path
                          (or the resolved path to --match if specified).
                          Default is a path under the cloudpack cache.
--disable-source-maps   Disable source maps.
--log-bundle-info       Write log files in each package's output folder with
                          bundle input, output, and info.

Examples

The examples below cover some common scenarios. Most of the options should work in combination with other ones even if not covered by examples.

bash

# Bundle the package in the current folder (output in cloudpack cache)
cloudpack bundle

# Make a production bundle of the current package (all dependencies included)
# output to dist/browser-esm
cloudpack bundle --mode prod --outdir dist/browser-esm

# Bundle all packages called "foo" and "bar" (exact string match, any version,
# output in cloudpack cache)
cloudpack bundle --match foo bar

# Bundle foo@1.2.3 with rspack (output in cloudpack cache)
cloudpack bundle --match foo@1.2.3 --bundler rspack

# Bundle all packages starting with @scope/
# (quotes required to prevent shell expansion; output in cloudpack cache)
cloudpack bundle --match '@scope/*'

`cache`

Handles operations related to the Cloudpack cache (requires a sub-command).

Usage: cloudpack cache <command>

To customize the cache directory, use cloudpack config set.

`clean` (`clear`)

Clears the Cloudpack cache.

Usage: cloudpack cache clean or cloudpack cache clear

`config`

Manage Cloudpack user preferences (requires a sub-command).

Usage: cloudpack config <command> [args]

Preferences are stored under <home>/.cloudpack.preferences.json.

Sub-commands

set <key> <value>   Set a user preference.
get <key>           Get a user preference.
list                List the current user preferences.
delete|unset <key>  Delete a user preference.

Available preferences

Name	Description
`cachePath`	Absolute path to the cache folder, instead of the default `<home>/.cloudpack`

`sync`

Syncs the packages from/to the remote cache. By default (without --upload) it will download any packages not found in the local cache.

Usage: cloudpack sync [options]

Options

Common options also apply.

txt

--upload    Upload packages to the remote cache (instead of downloading).
--login     How to authenticate against the remote cache.
              (choices: "interactive", "azure-cli", "device-code")
              Default: "azure-cli" in CI, "device-code" in Github Codespaces,
              "interactive" otherwise

`setup`

Configure certs and host file settings for cloudpack start if your server config sets https: true and/or has a custom domain. This command is intended to be used only on local developer machines and must be run with administrator/root privileges.

Usage: cloudpack setup [options]

setup workflow details

Options

Common options also apply.

txt

--force     Force execution of setup steps.

`report`

Report telemetry data (requires a sub-command).

Usage: cloudpack report <command>

`legacy-start`

Report the start of a legacy app. This is useful to track cloudpack vs legacy start usage.

Usage: cloudpack report legacy-start

Command line ​

Common options ​

init ​

Options ​

start ​

Options ​

Examples ​

link ​

Options ​

unlink ​

Options ​

bundle ​

Options ​

Examples ​

cache ​

clean (clear) ​

config ​

Sub-commands ​

Available preferences ​

sync ​

Options ​

setup ​

Options ​

report ​

legacy-start ​

Command line

Common options

`init`

Options

`start`

Options

Examples

`link`

Options

`unlink`

Options

`bundle`

Options

Examples

`cache`

`clean` (`clear`)

`config`

Sub-commands

Available preferences

`sync`

Options

`setup`

Options

`report`

`legacy-start`