Skip to content

02. CLI commands

Jump to bottom
isc-tleavitt edited this page Nov 20, 2024 · 13 revisions

Available commands:

arrange

Rearranges the resources in a module manifest to follow the standard format. Must either specify a module by name or use the -all flag.

Command: arrange [flags] [<module>]

Arguments:

  • module
    Name of module to rearrange

Flags:

  • -all
    Rearrange all modules loaded in development mode (rather than just the current one)

Examples:

  • arrange my-module
    Arranges module called my-module

  • arrange -all
    Arranges all modules

compile

This command is an alias for module-action module-name compile

Command: compile [flags] <module>

Arguments:

  • module
    Name of module on which to perform compile action

Flags:

  • -only, -o
    Only runs the specified phase (compile), rather than also running predecessors.
  • -dev
    Sets the DeveloperMode flag for the module's lifecycle. Key consequences of this are that ^Sources will be configured for resources in the module, and installer methods will be called with the dev mode flag set.
  • -quiet, -q
    Produces minimal output from the command.
  • -verbose, -v
    Produces verbose output from the command.

Examples:

  • compile my-module
    Compiles module called my-module

  • compile -o -v my-module
    Runs only the compile phase for module my-module and produces verbose output

config

Update IPM settings. The setting is a key-value pair.

Command: config <action> [<key> [<value>]]

Arguments:

  • action
    One of settings actions: list, get, set, delete
  • key
    Setting key
  • value
    Setting value

Examples:

  • config set analytics 0
    Disable collecting analytics data
    (Note: this may prevent an issue with long hangs at the end of zpm install with %objlasterror= "ERROR #6059: Unable to open TCP/IP socket to server www.google-analytics.com:80")

  • config set analytics 1
    Enable collecting analytics data

  • config list
    List all settings

  • config get analytics
    Get value for analytics key

  • config delete analytics
    Reset to default value for analytics key

default-modifiers

Manages default modifiers to use for all package manager commands in the current namespace.

Command: default-modifiers [flags]

Flags:

  • -set
    Set the default modifiers to the provided modifiers. Note: this just appends to existing modifiers. DOES NOT delete any defaults.
  • -get
    Prints the default modifiers to the current device.
  • -delete
    Deletes all registered default modifiers.

Examples:

  • default-modifiers -set -DNoTransaction=1 -DUpdateSnapshots=1
    Set custom modifiers "-DNoTransaction=1" and "-DUpdateSnapshots=1" with every package manager command. Note: modifiers starting with the prefix "D" are put into the "data" subscript of the command array.

  • default-modifiers -get
    Get currently set custom modifiers.

  • default-modifiers -delete
    Delete currently set custom modifiers.

enable

Enables IPM in other namespaces from a namespace in which IPM is already installed.

First IPM version with this command: 0.9.0

Command: enable [flags]

Flags:

  • -version, -v <value>
    A specific version of IPM can be provided. If not specified, the latest version from the registry will be installed (hence is not required if quiet flag is set).
  • -namespaces, -ns <value>
    Comma-separated namespaces in which IPM needs to be enabled.
  • -globally
    Will install IPM in all non-%SYS explicit namespaces that currently do not have IPM installed. By default, this modifier is not set and will not install globally.
  • -local-only
    If specified, only local artifacts will be used for installation. By default, this modifier is not set and will not limit to local artifacts.
  • -allow-upgrade
    If specified, will also check for IPM version in specified namespaces and upgrade if version is lower than the target version. By deafult, this modifier is not set and will not allow upgrade.
  • -quiet, -q
    Quiet mode. By default, this modifier is not set and will display the contents onto the terminal/caller command line.

Examples:

  • enable -globally -map
    Installs IPM in all explicit namespaces (including %SYS) by adding mappings to the current namespace's default routine database.
  • enable -v 1.3.4 -q -ns NS1,NS2,NS3
    Installs IPM version 1.3.4 quietly in namespaces: NS1, NS2, NS3.
  • enable -globally
    Installs IPM in all non-%SYS explicit namespaces, with version selected later in terminal prompt menu.
  • enable -v latest -globally Gets the latest version of IPM from the registry server, and install it in all non-%SYS explicit namespaces.
  • enable -v latest -allow-upgrade NS1,NS2,NS3 Installs or upgrade IPM to latest IPM version in namespaces: NS1, NS2, NS3.

exec

Executes the provided ObjectScript expression.

Command: exec <expression>

Alias: cos

Arguments:

  • expression
    ObjectScript expression(s) to execute

Examples:

  • exec set $Namespace = "MYAPP"
    Run the ObjectScript expression to set the namespace to MYAPP

  • exec write !,"Hello world!"
    Run the ObjectScript expression to print out the string Hello world!

generate

Generates module.xml

Command: generate [flags] [<path>]

Alias: gen

Flags:

  • -template, -t
    Generates module.xml template in the specified folder

  • -author, -a
    Request information about the author

Arguments:

  • path
    Directory on the local filesystem, where the module.xml file will be created

Examples:

  • generate
    Generates module.xml for your module in interactive mode

  • generate -t /my/path
    Generates template in the specified folder /my/path

help

Displays help information for the shell or a particular command

Command: help [flags] [<command>]

Alias: ?

Flags:

  • -markdown, -,
    Print detail in markdown format (for easy transfer to external documentation)

  • -verbose, -v
    Show full detail

Arguments:

  • command
    Command for which help information should be displayed

Examples:

  • help -v install
    Display full detail help information for the command install

import

Imports classes from a file or file(s), reexporting to source control if needed.

Command: import [flags] <source>

Arguments:

  • source
    File or directory to import

Flags:

  • -quiet, -q
    Produces minimal output from the command.

  • -verbose, -v
    Produces verbose output from the command.

  • -norecurse
    If importing a directory, do not recurse (default is to load directories recursively)

  • -nocompile
    Skip compiling imported classes (default is to compile them)

Examples

  • import C:\Temp\MyExport.xml
    Import and compile the class or classes from the given file

  • import C:\Temp\MyFlatExportDir\ -norecurse -nocompile
    Import the classes from the given directory, located at its root level only. Classes are loaded but not compiled.

init

Configures new namespace for use of package manager (interactive). This sets up the local cache and allows for configuration of studio extensions for source control and the package manager itself. In the case of Perforce-based source control, prompts are included for username, password, Perforce workspace, and a few other settings.

Command: init [flags]

Alias: initialize

Flags:

  • -noprompt, -quiet, -q
    If specified, no prompts will be shown.

  • -zpm, -cli
    If specified, the zpm command will be configured.

  • -extension, -ext <value>
    Generic extension (e.g., extension class for source control) to configure for the current namespace

  • -menuextension, -menuext <value>
    Server menu extension (Package Manager extension for server menus such as Studio, vscode menu, etc.) to configure for the current namespace

install

Installs a module available in a configured repository

Command: install [flags] [<registry-name>/]<module> [<version>]

Flags:

  • -dev
    Sets the DeveloperMode flag for the module's lifecycle. Key consequences of this are that ^Sources will be configured for resources in the module, and installer methods will be called with the dev mode flag set.

  • -keywords <value>, -k
    Searches for modules matching some set of keywords.

  • -quiet, -q
    Produces minimal output from the command.\

  • -verbose, -v
    Produces verbose output from the command.

Arguments:

  • registry-name
    Name of registry to install module from. Use repo -list to see configured registries.

  • module
    Name of module to install

  • version
    Version (or version expression) of module to install; defaults to the latest available if unspecified.

Examples:

  • install restforms2
    Installs the most recent version of restforms2 available in any configured repository in the current namespace.

list-dependents

Lists modules dependent on the specified module

Command: list-dependents [flags] <module> [<version>]

Alias: dependents

Flags:

  • -repos <value>, -r
    Comma-separated list of repository names to search in. If unspecified, the version of the module in the current namespace will be used instead.

  • -tree, -t
    If specified, show as a tree (rather than a flattened list)

Arguments:

  • module
    Name of module for which dependent modules will be found

  • version
    Version of the module for which dependent modules will be found (in all configured repositories)

Examples:

  • list-dependents HS.JSON
    Lists all currently-installed modules dependent on the currently-installed 'HS.JSON' version

  • list-dependents -repos AppModules HS.JSON
    Lists all modules in the 'AppModules' repository dependent on all 'HS.JSON' versions.

  • dependents -t -r AppModules HS.JSON 0.0.1+snapshot
    Lists all modules in the 'AppModules' repository dependent on 'HS.JSON' version '0.0.1+snapshot', as a tree.

list-installed

Lists modules installed in the current namespace

Command: list-installed [flags]

Alias: list

Flags

  • -tree, -t
    If specified, show dependency tree for installed modules

Examples

  • list-installed -tree
    Shows all installed modules in tree format.

load

Loads a module from the specified directory or archive into the current namespace. Dependencies are also loaded automatically, provided that they can be found in repositories configured with the 'repo' command.

Command: load [flags] <path>

Flags:

  • -dev
    Sets the DeveloperMode flag for the module's lifecycle. Key consequences of this are that ^Sources will be configured for resources in the module, and installer methods will be called with the dev mode flag set.

  • -quiet, -q
    Produces minimal output from the command.

  • -verbose,-v
    Produces verbose output from the command.

Arguments:

  • path
    Directory on the local filesystem, containing a file named module.xml

Examples:

  • load C:\module\root\path\
  • load C:\module\root\path\module-0.0.1.tgz
    Loads the module described in C:\module\root\path\module.xml
  • load -dev -verbose C:\module\root\path\
  • load -dev -verbose C:\module\root\path\module-0.0.1.tgz
    Loads the module described in C:\module\root\path\module.xml in developer mode and with verbose output.

Tarballs:

Tarballs can be downloaded manually from the package page on OpenExchange or from calling the IPM registry REST API using this format:

https://pm.community.intersystems.com/download/<package-name>/-/<package-name>-<package-version>.tgz

e.g. here is the URL for git-source-control:

https://pm.community.intersystems.com/download/git-source-control/-/git-source-control-2.3.0.tgz

module-action

Performs operations on modules - compiling, running tests, packaging/registering, etc.

module-action <module> <actions> [flags]

You can use this by starting a command with the module name.

<module> <actions> [flags]

Note that flags appear after all actions.

The standard lifecycle phases are:

  • clean: removes all dependencies that are not required by other installed modules and their resources. Dependencies required by other modules will also be removed if the -DClean.Force=1 flag is specified.
  • reload: pulls module source code into the namespace from disk. Does not compile.
  • validate: ensures that module API section is up to date, that module resource processor attributes are valid, and that the resources exported to the filesystem (and possible to source control) are consistent with what is in the database.
  • compile: compiles all resources within the module.
  • activate: performs post-compilation installation/configuration steps.
  • test: runs any unit tests associated with the module, in the current namespace.
  • package: exports the module's resources and bundles them into a module artifact (.tgz file).
  • verify: installs that artifact in a separate namespace, then runs integration tests (if any).
  • register: saves that artifact into the current namespace's module cache. This is accessible to other instances configured to look at the current namespace as a module repository.
  • publish: saves that artifact to the repository for which deployment is enabled. Currently, there may only be one of these per namespace.

Flags:

  • -dev
    Sets the DeveloperMode flag for the module's lifecycle. Key consequences of this are that ^Sources will be configured for resources in the module, and installer methods will be called with the dev mode flag set.
  • -only, -o
    Only runs the specified phase(s), rather than also running predecessors.
  • -quiet, -q
    Produces minimal output from the command.
  • -verbose, -v
    Produces verbose output from the command.

Arguments:

  • module
    Name of module on which to perform lifecycle actions
  • actions
    Space-delimited list of module lifecycle phases to run

Examples:

  • module-action MyModuleName compile
    Compiles the module named "MyModuleName"

  • MyModuleName clean register
    Performs multiple actions on the module named "MyModuleName"; "clean" deletes all of its dependenices, and "install" will then re-download them, package the module, and register it in the current namespace's module cache.

  • MyUIModule compile -v -Dmyparam=42
    Compiles the module named MyUIModule with verbose output and pParams("myparam") (passed to all lifecycle phases) set to 42.

namespace

See list modules in namespace and go to the namespace

Command: namespace [flags] [<name>]

Alias: zn

Arguments:

  • name
    Name of namespace, * or context name*

Flags:

  • -description, -d
    Shows description for each module.

Examples

  • zn *
    Show all modules in all namespaces

  • zn sql*
    Show all modules in namespaces by context

orphans

Lists resources in the current namespace's default code database that are not part of any module.

Command: orphans [flags]

Flags:

  • -type <value>, -t
    Type (e.g., extension) of resource to show; if unspecified, all types are included.

Examples:

  • orphans -type CLS
    Lists orphan files with extension CLS

package

This command is an alias for module-action module-name package

Command: package [flags] <module>

Arguments

  • module
    Name of module on which to perform package actions

Flags:

  • -only, -o
    Only runs the specified phase (package), rather than also running predecessors.
  • -dev
    Sets the DeveloperMode flag for the module's lifecycle. Key consequences of this are that ^Sources will be configured for resources in the module, and installer methods will be called with the dev mode flag set.
  • -quiet, -q
    Produces minimal output from the command.
  • -verbose, -v
    Produces verbose output from the command.
  • -path, -p <value>
    Use specified path to export package.

publish

This command is an alias for module-action module-name publish

Command: publish [flags] <module>

Arguments:

  • module
    Name of module on which to perform publish actions

Flags:

  • -only, -o
    Only runs the specified phase (publish), rather than also running predecessors.
  • -dev
    Sets the DeveloperMode flag for the module's lifecycle. Key consequences of this are that ^Sources will be configured for resources in the module, and installer methods will be called with the dev mode flag set.
  • -quiet, -q
    Produces minimal output from the command.
  • -verbose, -v
    Produces verbose output from the command.

quit

Exits the package manager shell

Command: quit

Aliases: q, exit

reinstall

Reinstalls an already-installed module from the latest version available in a configured repository. By default, updates dependencies of that module as well.

Command: reinstall [flags] <module>

Arguments:

  • module: Name of module to reinstall

Flags:

  • -dev
    Sets the DeveloperMode flag for the module's lifecycle. Key consequences of this are that ^Sources will be configured for resources in the module, and installer methods will be called with the dev mode flag set.
  • -quiet, -q
    Produces minimal output from the command.
  • -verbose, -v
    Produces verbose output from the command.
  • -shallow, -s
    Suppresses updating of dependencies with '+snapshot' versions.

Examples:

  • reinstall -dev ZHSLIB
    Reinstalls the currently-installed version of the ZHSLIB module, in development mode

reload

This command is an alias for module-action module-name reload

Command: reload [flags] <module>

Arguments:

  • module
    Name of module on which to perform reload action

Flags:

  • -only, -o
    Only runs the specified phase (reload), rather than also running predecessors.
  • -dev
    Sets the DeveloperMode flag for the module's lifecycle. Key consequences of this are that ^Sources will be configured for resources in the module, and installer methods will be called with the dev mode flag set.
  • -quiet, -q
    Produces minimal output from the command.
  • -verbose, -v
    Produces verbose output from the command.

repo

Configures the current namespace to search for modules on a remote server or on the local filesystem.

Command: repo [flags]

Alias: repository

Flags:

  • -app <value>
    When enabling a namespace to serve as a remote repository, specifies the web application to allow web service access.

  • -delete
    Deletes the current namespace's reference to the named repository

  • -delete-all
    Deletes all repositories (possibly subject to a type filter: -f, -r, -l)

  • -depth <value>, -d
    For filesystem repositories, specifies the depth (number of folders underneath the root) to search for files named module.xml

  • -filesystem, -f, -fs
    Create/update a filesystem repository

  • -list
    Lists all repositories (possibly subject to a type filter: -f, -r, -l)

  • -list-modules
    List modules available in the specified repository (-n[ame]), or in all configured repositories if no repository was specified.

  • -local, -l
    Create/update the local namespace cache

  • -name <value>, -n
    Namespace-unique name for the module

  • -password <value>, -pass
    For remote repositories, specifies the password to use when connecting.

  • -path <value>, -p
    For filesystem repositories, specifies the path to the root directory

  • -prereleases <0/1>, -pre
    For any repository, specifies that it should be used to look for prerelease software

  • -publish <0/1>
    When configuring a remote repository, specifies that publishing of packages to the repository is allowed. When configuring the current namespace with -enable, specifies that publishing is also enabled.

  • -remote, -r
    Create/update a remote server repository

  • -reset-defaults
    Reset to default remote repository

  • -snapshots <0/1>, -s
    For any repository, specifies that it should be used to look for snapshot builds (i.e., those with a semantic version ending in '+snapshot', indicating a 'latest' build of a particular version).

  • -type <value>, -t
    Subclass of %ZPM.PackageManager.Client.ServerDefinition to create/modify/delete or implementation of %ZPM.PackageManager.Core.IPackageService or %ZPM.PackageManager.Core.IPublishService to enable/disable

  • -url <value>
    For remote repositories, specifies the URL for package retrieval web services.

  • -username <value>, -user
    For remote repositories, specifies the username to use when connecting.

Examples:

  • repo -list
    List all repositories

  • repo -delete-all
    Delete all repositories

  • repo -name LocalFiles -snapshots 1 -fs -depth 2 -path C:\MyWorkspace\RootModuleDir\
    Create a repository pointing to the filesystem named "LocalFiles", accepting snapshots, looking for files named "module.xml" up to 2 directories deep in C:\MyWorkspace\RootModuleDir\

  • repo -n LocalFiles -delete
    Delete the repository named "LocalFiles"

  • repo -n AppModules -list-modules
    Lists all modules (and versions) available from the repository named "AppModules"

  • repo -r -n registry -reset-defaults
    Reset to default registry (pm.community.intersystems.com); it is equivalent to this command:
    repo -r -n registry -url https://pm.community.intersystems.com/ -user "" -pass ""

run-from-file

Imports either a text file or a JSON file that contains Package Manager Shell commands and runs them sequentially in the current namespace.

Expected format if the file is a text file (with a .txt extension):
    Each line of the file should contain a single command to be run

Expected format if the file is a JSON file (with a .json extension):
    The file must contain a single array whose items are JSON objects matching the following format:

{
      "command": "command name",
      "parameters": { ... },
      "modifiers": { ... },
      "custom_modifiers": { ... }
}

where each nested object contains key-value pairs. Note that for modifiers that have no value associated with them (such as -verbose), the value of the key-value pair for the modifier is ignored.

Command: run-from-file [flags] <file>

Alias: run

Arguments:

  • file
    File to import

Flags:

  • -dry-run, -d
    Does not actually run the commands. Simply displays what would be run.

Examples:

  • run-from-file C:\Temp\MyCommands.text
    Run the commands present in the text file, whose contents are as follows:
repo -name Test -p4 -path //Users/test/
install -dev TestModule -latest -DNoMapping=1 -DDeploy.Parameter="TESTDEPLOY"
  • run C:\Temp\MyCommands.json
    Run the commands present in the JSON file, whose contents are as follows:
{
      "commands": [
            {
                  "command": "repo",
                  "modifiers": {
                        "name": "Test",
                        "p4": "",
                        "path": "//Users/test/"
                  }
            },
            {
                  "command": "install",
                  "parameters": {
                        "module": "TestModule"
                  },
                  "modifiers": {
                        "dev": "",
                        "latest": ""
                  },
                  "custom_modifiers": {
                        "NoMapping": 1,
                        "Deploy.Parameter": "TESTDEPLOY"
                  }
            }
      ]
}

search

Shows all modules in current registry

Command: search

Alias: find

Flags:

  • -show-repo, -r
    Shows github repository for each module.

Examples:

  • search
    Shows all modules in current registry

test

Runs the unit tests for a module that are specified to run in the test phase.

Command: test <module>

Arguments

  • module
    Name of a module to run tests

Examples

  • test my-module
    Runs the test phase tests for my-module

uninstall

Uninstalls a module currently installed locally. This will be prevented if other modules depend on the named module, unless the -force flag is specified.

Command: uninstall [flags] <module>

Flags:

  • -force, -f
    If specified, the module will be uninstalled even if other modules depend on it.

  • -purge
    Purge data from tables during uninstall.

  • -quiet, -q
    Produces minimal output from the command.

  • -recurse, -r
    Also recursively uninstall dependencies. By default, will not uninstall dependencies that are also required by other installed modules; the -force flag overrides this.

  • -verbose, -v
    Produces verbose output from the command.

Arguments

  • module
    Name of a module to uninstall

Examples

  • uninstall restforms2
    Uninstalls restforms2 from the current namespace.

unpublish

Delete package from registry

Command: unpublish [flags] <module> <version>

Arguments:

  • module
    Name of module on which to perform unpublish actions
  • version
    Version of module on which to perform unpublish actions. Use "all" to delete all versions of the package

Flags:

  • -quiet, -q
    Produces minimal output from the command.
  • -verbose, -v
    Produces verbose output from the command.

Examples

  • unpublish MyModuleName all
    Delete all versions of the package "MyModuleName" from the registry
  • unpublish MyModuleName 1.0.0
    Delete version "1.0.0" of the package "MyModuleName" from the registry

verify

Runs the unit tests for a module that are specified to run in the verify phase.

Command: verify <module>

Arguments

  • module
    Name of a module to run tests in

Examples

  • verify my-module
    Runs the verify phase tests for my-module

version

Prints the currently-installed package manager and registry version

Command: version

Alias: ver

Examples:

  • version
Clone this wiki locally