The Adapt CLI is a command line interface for use with the Adapt framework. Its primary usefulness is to install, update, and uninstall Adapt plug-ins. In doing so, it references the Adapt Plugin Browser. Consequently, the CLI includes several commands for working with this plug-in registry.
IMPORTANT: The Adapt CLI is not intended to be used with courses in the Adapt authoring tool. The authoring tool tracks versions of plug-ins in its database. Using the CLI bypasses this tracking.
Before installing the Adapt CLI, you must install NodeJS and git.
To install the Adapt CLI globally, run the following command:
npm install -g adapt-cli
Some systems may require elevated permissions in order to install a script globally.
adapt version
This command reports both the version of the CLI and the version of the Adapt framework. The version of the framework is reported as "0.0.0" unless the command is run from the root directory of an installed framework.
adapt help [<command>]
command: A CLI command.
-
To list all the CLI commands with a brief description of each:
adapt help
-
To report a brief description of a specific command:
adapt help create
adapt create [<type> <path> <branch>]
type: What to create. Acceptable values are course
and component
.
path: The directory of the new course. Enclose in quotes if the path/name includes spaces.
branch: The branch of the framework to be downloaded. This is optional. If not specified, the master branch will be used.
-
To create an Adapt course (do not use in conjunction with the Adapt authoring tool):
adapt create course "My Course"
This will create a new directory named "My Course" in your current working directory. It will download the Adapt framework from its master branch, including the default course, into the new directory. Before using the course, run:
grunt build
-
To create an Adapt course from a specific branch:
adapt create course "My Course" develop
This is the same as example 1 except that the framework will be downloaded from its develop branch, not from the default master branch. -
To create an empty component:
adapt create component "test-component"
This command is useful for developing new components. It will create a new directory named "test-component" in the current working directory. It will populate the directory with files required for an Adapt component and insert "test-component" into the code where required.
adapt search [<plug-in>]
plug-in: The optional name of the plug-in that you want to search for. Any part of the name may be used; multiple results may be returned if the partial name is not unique.
The search command searches within Adapt Plugin Browser. It will return the plug-in's complete name and its source repository only if the plug-in is registered.
-
To view the name and repository of all plug-ins registered with the Adapt Plugin Browser:
adapt search
-
To locate the repository of a known plug-in that is registered:
adapt search adapt-contrib-pageLevelProgress
OR
adapt search contrib-pageLevelProgress
OR
adapt search pageLevel
adapt install <plug-in>[#|@<version>]
adapt install [--dry-run|--compatible]
plug-in: The name of the plug-in to be installed. The name may be fully qualified with "adapt-" or the prefix may be omitted. Parts of names are not acceptable.
version: A specific version number of the plug-in. This is optional.
-
To install all plug-ins listed in adapt.json:
adapt install
This command must be run in the root directory of an Adapt framework installation. -
To report the plug-ins that will be installed if
adapt install
is run:
adapt install --dry-run
This command must be run in the root directory of an Adapt framework installation. -
To install versions of all plug-ins listed in adapt.json that are compatible with the installed framework version. This overrides any incompatible settings provided on the command line or in adapt.json.
adapt install --compatible
This command must be run in the root directory of an Adapt framework installation. -
To install a plug-in that has been registered with the Adapt Plug-in Browser registry:
adapt install adapt-contrib-pageLevelProgress
OR
adapt install contrib-pageLevelProgress
-
To install a specific version of a registered plug-in:
adapt install adapt-contrib-pageLevelProgress#1.1.0
OR
adapt install [email protected]
OR
adapt install contrib-pageLevelProgress#1.1.0
OR
adapt install [email protected]
-
To use the CLI to install a plug-in that is not registered with Adapt Plug-in Browser registry:
- Copy the uncompressed folder to the proper location for the type of plug-in. Components: src/components. Extensions: src/extensions. Menu: src/menu. Theme: src/theme. Note: The Adapt framework allows only one theme. Uninstall the current before replacing it with an alternative. More than one menu is allowed.
- Open adapt.json in an editor and add the full name of the new component to the list.
- Run the following command from the course root:
adapt install
After installation, most CLI commands will operate on the plug-in with the exception ofadapt update
. Plug-ins must be registered with the Adapt Plugin Browser foradapt update
to succeed.
-
To update all registered plug-ins to their most recent public release:
adapt update
Since no plug-in name is specified in this command, all plug-ins listed in adapt.json are reinstalled. Whether the plug-in is updated will be determined by the compatible framework versions specified in adapt.json. If it includes a plug-in that is not registered, it will not be updated.
Note to developers: The CLI determines newest version by comparing release tags in the GitHub repo. Be sure to use a tag when you release a new version.
adapt ls
This command lists the name and version number of all plug-ins listed in the adapt.json file of the current directory.
adapt uninstall <plug-in>
plug-in: The name of the plug-in to be installed. The name may be fully qualified with "adapt-" or the prefix may be omitted. Parts of names are not acceptable.
- To uninstall a plug-in:
adapt uninstall adapt-contrib-pageLevelProgress
OR
adapt uninstall contrib-pageLevelProgress
Because the plug-in registry is not referenced during the uninstall process, this command will work whether or not the plug-in is registered with the Adapt Plugin Browser..
adapt devinstall [<plug-in>[#<version>]]
plug-in: Name of the plug-in to be cloned.
version: Version of the plug-in to be installed.
-
To clone as git repositories the Adapt framework and all the plug-ins listed in adapt.json of the current directory:
adapt devinstall
-
To clone a specific plug-in listed in the adapt.json:
adapt devinstall adapt-contrib-matching
-
To clone a specific version of a plug-in listed in the adapt.json:
adapt devinstall adapt-contrib-matching#v2.2.0
adapt update [<plug-in>[#|@<version>]][--check]
adapt update [components|extensions|menu|theme|all][--check]
plug-in: Name of the plug-in to be cloned.
version: Version of the plug-in to be installed.
Before running the update command, ensure that there is no bower.json file in your project directory.
-
To report the latest compatible version for each plug-in in the current directory (plug-ins are not updated):
adapt update --check
Note: The--check
option may be used to report on a specific plug-in or on a complete plug-in group (components, extensions, theme, menu):
adapt update adapt-contrib-matching --check
adapt update extensions --check
-
To update a registered plug-in:
adapt update adapt-contrib-pageLevelProgress
OR
adapt update contrib-pageLevelProgress
-
To update a specific version of a registered plug-in:
adapt update adapt-contrib-pageLevelProgress#1.1.0
OR
adapt update [email protected]
OR
adapt update contrib-pageLevelProgress#1.1.0
OR
adapt update [email protected]
adapt register
This command must be run from within the root directory of the plug-in you want to register. "name" and "repository" will be read from bower.json in the current directory. The plug-in name must be prefixed with "adapt-" and each word separated with a hyphen (-). Plug-in names are checked against those already registered to avoid duplicates.
URL format must be of the form git://github.com/<user>/<repo_name>.git
adapt rename <current-name> <new-name>
current-name: Name of the plug-in currently used in the plug-in registry.
new-name: Name proposed to replace the current plug-in name.
Please note that you must authenticate with GitHub to use rename. You must be a collaborator on the endpoint registered with the plug-in or a collaborator on the Adapt framework. Access to GitHub is for authentication only.
- To rename a plug-in:
adapt rename adapt-incorrectName adapt-betterName
adapt unregister [<plug-in>]
plug-in: Name of the plug-in currently used in the plug-in registry.
Please note that you must authenticate with GitHub to use unregister. You must be a collaborator on the endpoint registered with the plug-in or a collaborator on the Adapt framework. Access to GitHub is for authentication only.
-
To unregister a plug-in while in the root directory of the plug-in:
adapt unregister
-
To unregister a plug-in by name:
adapt unregister adapt-myMistake
The Adapt community maintains the Adapt Plugin Browser as a convenient registry of components, extensions, themes, and menus. The plug-in system is powered by Bower: http://adapt-bower-repository.herokuapp.com/packages/. To register, a plug-in must be a valid bower package with bower.json, and have a unique name that is prefixed with "adapt-".
See Developing plug-ins for more information on defining your plug-in's package and on registering your plug-in.
Version number: 2.1.4
Author / maintainer: Adapt Core Team with contributors