{"id":22729868,"url":"https://github.com/jhpyle/docassemblecli","last_synced_at":"2025-04-13T23:13:56.709Z","repository":{"id":38327226,"uuid":"342953474","full_name":"jhpyle/docassemblecli","owner":"jhpyle","description":"CLI utilities for using docassemble","archived":false,"fork":false,"pushed_at":"2025-03-09T20:28:43.000Z","size":98,"stargazers_count":13,"open_issues_count":1,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-13T23:13:43.139Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jhpyle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-02-27T20:37:41.000Z","updated_at":"2025-03-26T23:33:24.000Z","dependencies_parsed_at":"2023-12-03T21:22:45.192Z","dependency_job_id":"aaf6c736-91a6-41a4-89cf-7a42af15f8bc","html_url":"https://github.com/jhpyle/docassemblecli","commit_stats":{"total_commits":33,"total_committers":6,"mean_commits":5.5,"dds":"0.18181818181818177","last_synced_commit":"360172fc1c25d7d4b617e3ed568b2719b8f7c903"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhpyle%2Fdocassemblecli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhpyle%2Fdocassemblecli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhpyle%2Fdocassemblecli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jhpyle%2Fdocassemblecli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jhpyle","download_url":"https://codeload.github.com/jhpyle/docassemblecli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248794569,"owners_count":21162615,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-10T18:12:11.485Z","updated_at":"2025-04-13T23:13:56.685Z","avatar_url":"https://github.com/jhpyle.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docassemblecli\n\n`docassemblecli` provides command-line utilities for interacting with\n[docassemble] servers. This package is meant to be installed on your\nlocal machine, not on a [docassemble] server.\n\n## Prerequisites\n\nThe `dainstall`, `dacreate`, and `dadownload` utility programs require\nthat you have Python installed on your computer. If you are using\nMacOS or Linux, you probably have Python installed already.\n\n### Installing Python on Windows\n\nIf you are using Windows and you have not installed Python before, it\nis recommended that you download Python from the [python.org download\npage] rather than using the Microsoft Store. When you run the\ninstaller, there will be two checkbox options (\"Use admin privileges\nwhen installing py.exe\" and \"Add python.exe to PATH\"), and you should\ncheck both of them. Later on in the installation, you may be prompted\nto extend the maximum length of the `PATH` variable beyond 250\ncharacters. You should click the button to make this\nchange. Installing Python this way will make it much easier to run the\nutilities because you will not need to manually adjust your `PATH`.\n\nNote that when you have installed Python on Windows, an application\ncalled \"Python\" will be available from the start menu. This\napplication runs the [Python Interpreter]. The Python Interpreter is a\nvery useful tool, but it is not the tool for installing\n`docassemblecli` or running the command line utilities `dainstall`,\n`dacreate`, and `dadownload`. To run these commands, you need to use\nthe Windows command line application, called `cmd`.\n\n### Using a command line\n\nIn order to install `docassemblecli` and use the utilities, you will\nneed to run an application that gives you a command line. On MacOS,\nyou can use the [Terminal application], which comes with the operating\nsystem. On Windows, you can go to the start menu and search for \"cmd,\"\nwhich is the name of the [Windows command line application].\n\n## Installation\n\nTo install `docassemblecli` from PyPI, run:\n\n    pip3 install docassemblecli\n\nIf you get an error, you may not have installed Python, or may not\nhave installed it correctly. If you only have Python 2.7 installed,\ninstall the latest version of Python instead (e.g., Python 3.12 or\ngreater.) If you know you have installed Python, but `pip3` is not a\nrecognized command, you might need to manually adjust your `PATH`.\n\nTo upgrade `docassemblecli` after you have already installed it, do:\n\n    pip3 install --upgrade docassemblecli\n\n## Usage\n\n### dacreate\n\n`docassemblecli` provides a command-line utility called `dacreate`,\nwhich creates an empty **docassemble** add-on package.\n\nTo create a package called `docassemble-foobar`, run:\n\n    dacreate foobar\n\nYou will be asked some questions about the package and the\ndeveloper. This information is necessary because it goes into the\n`setup.py`, `README.md`, and `LICENSE` files of the package. If you do\nnot yet know what answers to give, just press enter, and you can edit\nthese files later.\n\nWhen the command exits, you will find a directory in the current\ndirectory called `docassemble-foobar` containing a shell of a\n**docassemble** add-on package.\n\nYou can run `dacreate --help` to get more information about how\n`dacreate` works:\n\n    usage: dacreate [-h] [--developer-name DEVELOPER_NAME]\n                    [--developer-email DEVELOPER_EMAIL]\n                    [--description DESCRIPTION] [--url URL] [--license LICENSE]\n                    [--version VERSION] [--output OUTPUT]\n                    [package]\n\n    positional arguments:\n      package               name of the package you want to create\n\n    options:\n      -h, --help            show this help message and exit\n      --developer-name DEVELOPER_NAME\n                            name of the developer of the package\n      --developer-email DEVELOPER_EMAIL\n                            email of the developer of the package\n      --description DESCRIPTION\n                            description of package\n      --url URL             URL of package\n      --license LICENSE     license of package\n      --version VERSION     version number of package\n      --output OUTPUT       output directory in which to create the package\n\n### dainstall\n\n`docassemblecli` provides a command-line utility called `dainstall`,\nwhich installs a Python package on a remote server using files on your\nlocal computer.\n\nFor example, suppose that you wrote a docassemble extension package\ncalled `docassemble.foobar` using the **docassemble** Playground. In\nthe Playground, you can download the package as a ZIP file called\n`docassemble-foobar.zip`. You can then unpack this ZIP file and you\nwill see a folder called `docassemble-foobar`. Inside of this folder\nthere is a folder called `docassemble` and a `setup.py` file. Your\ninterview YAML files will be in the folder\n`docassemble/foobar/data/questions`. Your templates will be in the\nfolder `docassemble/foobar/data/templates`. Your modules will be in\nthe folder `docassemble/foobar`. Now you can use your favorite text\neditor to edit your `.yml` and `.py` files, and you can use\n`dainstall` to install the package on your server so that you can test\nyour changes.\n\nFrom the command line, use `cd` to navigate to the folder that\ncontains the `docassemble-foobar` folder. Then run:\n\n    dainstall docassemble-foobar\n\nThe first time you run this command, it will ask you for the URL of\nyour **docassemble** server and the [API key] of a user with `admin` or\n`developer` privileges.\n\nIt will look something like this:\n\n    $ dainstall docassemble-foobar\n    Base URL of your docassemble server (e.g., https://da.example.com): https://dev.example.com\n    API key of admin user on http://localhost: H3PWMKJOIVAXL4PWUJH3HG7EKPFU5GYT\n    Saved base URL and API key to .docassemblecli\n    Waiting for package to install.............................\n    Installed.\n\nThe next time you run `dainstall`, it will not ask you for the URL and\nAPI key.\n\nYou can run `dainstall --help` to get more information about how\n`dainstall` works:\n\n    usage: dainstall [-h] [--apiurl APIURL] [--apikey APIKEY] [--norestart]\n                     [--watch] [--force-restart] [--server SERVER] [--playground]\n                     [--project PROJECT] [--add] [--noconfig] [--debug]\n                     [directory]\n\n    positional arguments:\n      directory\n\n    options:\n      -h, --help         show this help message and exit\n      --apiurl APIURL    base url of your docassemble server, e.g.\n                         https://da.example.com\n      --apikey APIKEY    docassemble API key\n      --norestart        do not restart the docassemble server after installing\n                         package (only applicable in single-server environments)\n      --watch            watch the directory for changes and install changes when\n                         there is a change\n      --force-restart    unconditionally restart the docassemble server after\n                         installing package\n      --server SERVER    use a particular server from the .docassemblecli config\n                         file\n      --playground       install into your Playground instead of into the server\n      --project PROJECT  install into a specific project in the Playground\n      --add              add another server to the .docassemblecli config file\n      --noconfig         do not use the .docassemblecli config file\n      --debug            use verbose logging\n\nFor example, you might want to pass the URL and API key in the command\nitself:\n\n    dainstall --apiurl https://dev.example.com --apikey H3PWMKJOIVAXL4PWUJH3HG7EKPFU5GYT docassemble-foobar\n\nIf you have more than one server, you can run:\n\n    dainstall --add\n\nto add an additional server configuration to store in your\n`.docassemblecli` config file. Then you can select the server using\n`--server`:\n\n   dainstall --server dev.example.com docassemble-foobar\n\nIf you do not specify a `--server`, the first server indicated in your\n`.docassemblecli` file will be used.\n\nThe `--norestart` option can be used when your **docassemble**\ninstallation only uses one server (which is typical) and you are not\nmodifying .py files. In this case, it is not necessary for the Python\nweb application to restart after the package has been installed. This\nwill cause `dainstall` to return a few seconds faster than otherwise.\n\nThe `--force-restart` option should be used when you want to make sure\nthat **docassemble** restarts the Python web application after the\npackage is installed. By default, `dainstall` will avoid restarting\nthe server if the package has no module files and all of its\ndependencies (if any) are installed.\n\nBy default, `dainstall` installs a package on the server. If you want\nto install a package into your Playground, you can use the\n`--playground` option.\n\n   dainstall --playground docassemble.foobar\n\nIf you want to install into a particular project in your Playground,\nindicate the project with `--project`.\n\n   dainstall --playground --project testing docassemble-foobar\n\nInstalling into the Playground with `--playground` is faster than\ninstalling an actual Python package because it does not need to run\n`pip`.\n\nIf you are using a multi-server configuration, it is safe to run\n`dainstall --playground` with `--norestart` if you are only changing\nYAML files, because Playground YAML files are stored in cloud storage\nand will thus be available immediately to all servers.\n\nYou can run `dainstall` with the `--watch` option if you want your\npackage to be automatically updated on the server every time a file in\nyour package directory is changed.\n\nFor example, suppose you run:\n\n    dainstall --watch --playground --project testing docassemble-foobar\n\nThis will monitor the `docassemble-foobar` directory, and if any file\nwithin the directory is modified, or a new file is created, the\npackage will be reinstalled into the `testing` project of the\nPlayground belonging to the owner of the API key.\n\nTo exit, type Ctrl-c.\n\nThe `--watch` feature tries to be as efficient as possible. If you\nmodify a file in the `data` folder, it will not restart the server\nafterward. However, it will restart the server if you modify a `.py`\nfile, because otherwise you would not be able to see the effect of the\nchange. If you are using `--playground`, the `dainstall --watch`\nfeature will only upload the specific file or files that you modified,\nrather than uploading the whole package.\n\nThus, for the fastest development experience, use `--watch` and\n`--playground`.\n\nIf you encounter problems, try running dainstall with the `--debug`\noption.\n\n### dadownload\n\nThe `dadownload` utility downloads a package from a **docassemble**\nserver and saves it to the current working directory. It connects to\na **docassemble** server in the same way that `dainstall` does.\n\n    usage: dadownload [-h] [--overwrite] [--apiurl APIURL] [--apikey APIKEY]\n                      [--server SERVER] [--playground] [--project PROJECT] [--add]\n                      [--noconfig]\n                      [package]\n\n    positional arguments:\n      package\n\n    options:\n      -h, --help         show this help message and exit\n      --overwrite        overwrite existing files\n      --apiurl APIURL    base url of your docassemble server, e.g.\n                         https://da.example.com\n      --apikey APIKEY    docassemble API key\n      --server SERVER    use a particular server from the .docassemblecli config\n                         file\n      --playground       download from the Playground\n      --project PROJECT  download from a specific project in the Playground\n      --add              add another server to the .docassemblecli config file\n      --noconfig         do not use the .docassemblecli config file\n\nFor example, if you run `dadownload docassemble.foo` (or `dadownload\nfoo`, which will do the same thing), a directory `docassemble-foo`\nwill be created, containing the `docassemble.foo` package that is\ninstalled on the **docassemble** server.\n\nIf you use `--playground`, then the files specified in a package in\nthe Packages folder of the Playground will be collected and downloaded\nto the current working directory.\n\nWithout `--playground`, the package that is installed on the server\nwill be downloaded to the current working directory. This only works\nif the package was installed by uploading a ZIP file. (Note that the\n`dainstall` command installs packages by uploading a ZIP file.) If the\npackage you want to download is on GitHub, use `git clone` to obtain\nit. If the package is only on PyPI, use `pip download` to download the\ncode.\n\nBy default, `dadownload` will not overwrite any existing files. You\ncan override this by specifying `--overwrite`.\n\n## Text editors that create hidden and temporary files\n\nText editors often create hidden files and hidden directories in your\nproject folder for their own purposes, such as backup files and files\nthat facilitate [linting]. This can be problematic when you are using\n`git`, because you do not want these temporary files to appear on\nGitHub. These files may cause `dainstall --watch` to think that a\nfile in your project has been modified, when it actually has not.\n\nThe `dainstall` command tries to avoid this. If you have `git`\ninstalled, `dainstall` will call `git ls-files` to see what your\n`.gitignore` file is screening out, and then tries to avoid these\nfiles. It also uses regular expressions to avoid certain files and\ndirectories.\n\nIf your development environment triggers `dainstall --watch` too much,\nsubmit a GitHub issue in the `jhpyle/docassemblecli` repository\nexplaining the situation. It may be possible to tweak the code to\navoid the unnecessary triggering.\n\n[API key]: https://docassemble.org/docs/api.html#manage_api\n[docassemble]: https://docassemble.org\n[python.org download page]: https://www.python.org/downloads/\n[Python Interpreter]: https://docs.python.org/3/tutorial/interpreter.html\n[Terminal application]: https://support.apple.com/guide/terminal/welcome/mac\n[Windows command line application]: https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/windows-commands\n[linting]: https://en.wikipedia.org/wiki/Lint_%28software%29\n[VS Code]: https://code.visualstudio.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhpyle%2Fdocassemblecli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjhpyle%2Fdocassemblecli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjhpyle%2Fdocassemblecli/lists"}