Package: docassemblecli
docassembleclidocassemblecliprovides command-line utilities for interacting withdocassembleservers. This package is meant to be installed on your
local machine, not on adocassembleserver.PrerequisitesThedainstallanddacreateprograms require that you have Python
installed on your computer. Thedawatchinstallprogram requiresbashandfswatch. These prerequisites are easy to find on Linux
machines, but are harder to install on Windows and Mac systems. If you
run Windows, see the last section of this README for instructions on
getting a command line in Windows Subsystem for Linux.InstallationTo installdocassembleclifrom PyPI, run:pip install docassemblecliUsagedacreatedocassemblecliprovides a command-line utility calleddacreate,
which creates an emptydocassembleadd-on package.To create a package calleddocassemble-foobar, run:dacreate foobarYou will be asked some questions about the package and the
developer. This information is necessary because it goes into thesetup.py,README.md, andLICENSEfiles of the package. If you do
not yet know what answers to give, just press enter, and you can edit
these files later.When the command exits, you will find a directory in the current
directory calleddocassemble-foobarcontaining a shell of adocassembleadd-on package.You can rundacreate --helpto get more information about howdacreateworks:usage: dacreate [-h] [--developer-name DEVELOPER_NAME]
                [--developer-email DEVELOPER_EMAIL]
                [--description DESCRIPTION] [--url URL] [--license LICENSE]
                [--version VERSION] [--output OUTPUT]
                [package]

positional arguments:
  package               name of the package you want to create

options:
  -h, --help            show this help message and exit
  --developer-name DEVELOPER_NAME
                        name of the developer of the package
  --developer-email DEVELOPER_EMAIL
                        email of the developer of the package
  --description DESCRIPTION
                        description of package
  --url URL             URL of package
  --license LICENSE     license of package
  --version VERSION     version number of package
  --output OUTPUT       output directory in which to create the packagedainstalldocassemblecliprovides a command-line utility calleddainstall,
which installs a Python package on a remote server using files on your
local computer.For example, suppose that you wrote a docassemble extension package
calleddocassemble.foobarusing thedocassemblePlayground. In
the Playground, you can download the package as a ZIP file calleddocassemble-foobar.zip. You can then unpack this ZIP file and you
will see a folder calleddocassemble-foobar. Inside of this folder
there is a folder calleddocassembleand asetup.pyfile.From the command line, usecdto navigate to the folder that
contains thedocassemble-foobarfolder. Then run:dainstall docassemble-foobarOn Windows, you will need to writepython -m docassemblecli.dainstallin place ofdainstall, so your command
will look like this:python -m docassemblecli.dainstall docassemble-foobarThe first time you run this command, it will ask you for the URL of
yourdocassembleserver and theAPI keyof a user withadminordeveloperprivileges.It will look something like this:$ dainstall docassemble-foobar
Base URL of your docassemble server (e.g., https://da.example.com): https://dev.example.com
API key of admin user on http://localhost: H3PWMKJOIVAXL4PWUJH3HG7EKPFU5GYT
Saved base URL and API key to .docassemblecli
Waiting for package to install.............................
Installed.The next time you rundainstall, it will not ask you for the URL and
API key.You can rundainstall --helpto get more information about howdainstallworks:usage: dainstall [-h] [--apiurl APIURL] [--apikey APIKEY] [--norestart]
                 [--force-restart] [--server SERVER] [--playground]
                 [--project PROJECT] [--add] [--noconfig]
                 [directory]

positional arguments:
  directory

options:
  -h, --help         show this help message and exit
  --apiurl APIURL    base url of your docassemble server, e.g.
                     https://da.example.com
  --apikey APIKEY    docassemble API key
  --norestart        do not restart the docassemble server after installing
                     package (only applicable in single-server environments)
  --force-restart    unconditionally restart the docassemble server after
                     installing package
  --server SERVER    use a particular server from the .docassemblecli config
                     file
  --playground       install into your Playground instead of into the server
  --project PROJECT  install into a specific project in the Playground
  --add              add another server to the .docassemblecli config file
  --noconfig         do not use the .docassemblecli config fileFor example, you might want to pass the URL and API key in the command
itself:dainstall --apiurl https://dev.example.com --apikey H3PWMKJOIVAXL4PWUJH3HG7EKPFU5GYT docassemble-foobarIf you have more than one server, you can run:dainstall --addto add an additional server configuration to store in your.docassemblecliconfig file. Then you can select the server using--server:dainstall --server dev.example.com docassemble-foobarIf you do not specify a--server, the first server indicated in your.docassembleclifile will be used.The--norestartoption can be used when yourdocassembleinstallation only uses one server (which is typical) and you are not
modifying .py files. In this case, it is not necessary for the Python
web application to restart after the package has been installed. This
will causedainstallto return a few seconds faster than otherwise.The--force-restartoption should be used when you want to make sure
thatdocassemblerestarts the Python web application after the
package is installed. By default,dainstallwill avoid restarting
the server if the package has no module files and all of its
dependencies (if any) are installed.By default,dainstallinstalls a package on the server. If you want
to install a package into your Playground, you can use the--playgroundoption.dainstall --playground docassemble.foobarIf you want to install into a particular project in your Playground,
indicate the project with--project.dainstall --playground --project testing docassemble-foobarInstalling into the Playground with--playgroundis faster than
installing an actual Python package because it does not need to runpip.If your development installation uses more than one server, it is safe
to rundainstall --playgroundwith--norestartif you are only
changing YAML files, because Playground YAML files are stored in cloud
storage and will thus be available immediately to all servers.How it worksThedainstallcommand is just a simple Python script that creates a
ZIP file and uploads it through thedocassembleAPI. Feel free to
copy the code and write your own scripts to save yourself time.Automatically callingdainstallYou can use thebashscriptdawatchinstallto calldainstallautomatically every time a file in your package directory is changed.For example, if you run:dawatchinstall --playground --project testing docassemble-foobarThis will monitor thedocassemble-foobardirectory, and if any file
changes, it will run:dainstall --playground --project testing --norestart docassemble-foobarIf a.pyfile is changed, however, it will rundainstall --playground --project testing docassemble-foobarWithdawatchinstall --playgroundconstantly running, then after you
save a YAML file on your local machine, it will be available for
testing on your server very quickly.To exitdawatchinstall, type Ctrl-c.To use this, bothdawatchinstallanddainstallneed to be in your
path; if it is not, you will need to edit thedawatchinstallscript
so that it can successfully call thedainstallscript.Thedawatchinstallscript depends on thefswatchcommand. If this
command is not available on your system, you may need to install thefswatchpackage.Running on WindowsIf you are running Windows, a relatively convenient way to install
these command-line utilities is to use Windows Subsystem for Linux.In the Microsoft Store, search for "Ubuntu" and install it. This may
require restarting your Windows machine. (Other Linux distributions
will work just as well, so feel free to use a different distribution
if you know what you are doing.)Then run the Ubuntu app and answer the prompts to complete the
installation.From the Ubuntu command line, do:sudo apt -y update
sudo apt -y install python3-pip fswatch
sudo pip install docassemblecli
dainstall --addThe last command,dainstall --add, will ask for your docassemble
site URL and your API key. The API key that you supply needs to belong
to a user withdeveloperoradminprivileges.Usecdto switch to the directory above where your docassemble
package is located. (Your Windows hard drive is located at/mnt/cinside of Ubuntu.)For example, assume you have a folderdocassemble-mypackageon your
Desktop, and your username on your machine isjsmith. You would do:cd /mnt/c/Users/jsmith/Desktop/From there, you can run commands like:dainstall docassemble-mypackageordawatchinstall --playground --project mypack docassemble-mypackage