{"id":47928276,"url":"https://github.com/jpagh/docassemblecli3","last_synced_at":"2026-04-04T07:02:37.343Z","repository":{"id":253572040,"uuid":"843623391","full_name":"jpagh/docassemblecli3","owner":"jpagh","description":"Multi-platform CLI utility for working with docassemble packages and servers.","archived":false,"fork":false,"pushed_at":"2026-03-20T16:36:34.000Z","size":133,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-21T08:04:54.784Z","etag":null,"topics":["docassemble"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/docassemblecli3/","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/jpagh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-08-17T00:03:09.000Z","updated_at":"2026-03-20T16:36:38.000Z","dependencies_parsed_at":"2024-09-11T17:23:22.285Z","dependency_job_id":"ea216d2f-ed2e-4982-bb44-75c93ead6712","html_url":"https://github.com/jpagh/docassemblecli3","commit_stats":null,"previous_names":["jpagh/docassemblecli3"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/jpagh/docassemblecli3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpagh%2Fdocassemblecli3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpagh%2Fdocassemblecli3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpagh%2Fdocassemblecli3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpagh%2Fdocassemblecli3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jpagh","download_url":"https://codeload.github.com/jpagh/docassemblecli3/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpagh%2Fdocassemblecli3/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31390695,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["docassemble"],"created_at":"2026-04-04T07:02:33.666Z","updated_at":"2026-04-04T07:02:37.290Z","avatar_url":"https://github.com/jpagh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docassemblecli3\r\n\r\n`docassemblecli3` provides command-line utilities for interacting with\r\n[docassemble] servers. This package is meant to be installed on your local\r\nmachine, not on a [docassemble] server.\r\n\r\nThis project is based on [docassemblecli] by Jonathan Pyle Copyright (c) 2021\r\nreleased under the MIT License.\r\n\r\n## Differences from [docassemblecli]\r\n\r\n- Requires Python 3.\r\n- Adds multi-platform file monitoring, a.k.a. `dawatchinstall` works on Windows\r\n  and without requiring fswatch.\r\n- Adds queueing and batching to improve file monitoring and installation\r\n  (improves multi-file saving, late file metadata changes, and avoids server\r\n  restart induced timeouts).\r\n- Improves invocation, requiring less configuration of PATH and scripts to work,\r\n  especially in Windows (and does not conflict with [docassemblecli]).\r\n- Improved command structure and option flags (so please read this documentation\r\n  or utilize the `--help` or `-h` options in the terminal).\r\n\r\n## Prerequisites\r\n\r\nThis program requires Python 3.12 or newer on your computer. It was developed\r\nand tested with Python 3.13. Use `uv` for local project management and command\r\nexecution.\r\n\r\n## Installation\r\n\r\nTo install `docassemblecli3`, run:\r\n\r\n    pip install docassemblecli3 \r\n\r\nTo install `docassemblecli3` as a tool with `uv`, run:\r\n\r\n    uv tool install docassemblecli3\r\n\r\nTo work on the project locally, create or update the environment with:\r\n\r\n    uv sync\r\n\r\nRun commands in the project environment with `uv run`, for example:\r\n\r\n    uv run pytest -q\r\n    uv run python -m docassemblecli3 --help\r\n\r\n## Usage\r\n\r\n`docassemblecli3` may be more easily be run by typing `da`.\r\n\r\nAll of the command options, such as showing the \"help\", have both long `--help`\r\nand short `-h` versions. This documentation will always use the long version,\r\nbut feel free to use whichever you prefer.\r\n\r\n    Usage: da [OPTIONS] COMMAND [ARGS]...\r\n\r\n    Commands for working with docassemble packages and servers.\r\n\r\n    Options:\r\n    --version                     Show the version and exit.\r\n    --bell / --no-bell            Play bell sound notification.  [default: bell]\r\n    -C, --color / -N, --no-color  Overrides color auto-detection in interactive\r\n                                    terminals.\r\n    -h, --help                    Show this message and exit.\r\n\r\n    Commands:\r\n    config   Manage servers in a docassemblecli config file.\r\n    create   Create an empty docassemble add-on package.\r\n    download Download a docassemble package from a docassemble server or Playground.\r\n    install  Install a docassemble package on a docassemble server.\r\n    uninstall Uninstall a docassemble package from a docassemble server.\r\n    watch    Watch a package directory and `install` any changes.\r\n\r\n### create\r\n\r\n`docassemblecli3` provides a command-line utility called `create`, which\r\ncreates an empty **docassemble** add-on package.\r\n\r\nTo create a package called `docassemble-foobar` in the current directory, run:\r\n\r\n    da create --package foobar\r\n\r\nYou will be asked some questions about the package and the developer. This\r\ninformation is necessary because it goes into the `pyproject.toml`, `setup.py`,\r\n`README.md`, and `LICENSE` files of the package. If you do not yet know what answers to give,\r\njust press enter, and you can edit these files later.\r\n\r\nWhen the command exits, you will find a directory in the current directory\r\ncalled `docassemble-foobar` containing a shell of a **docassemble** add-on\r\npackage.\r\n\r\nYou can run `da create --help` to get more information about how `create`\r\nworks:\r\n\r\n    Usage: da create [OPTIONS]\r\n\r\n    Create an empty docassemble add-on package.\r\n\r\n    Options:\r\n    --package PACKAGE          Name of the package you want to create\r\n    --developer-name NAME      Name of the developer of the package\r\n    --developer-email EMAIL    Email of the developer of the package\r\n    --description DESCRIPTION  Description of package\r\n    --url URL                  URL of package\r\n    --license LICENSE          License of package\r\n    --version VERSION          Version number of package\r\n    --output OUTPUT            Output directory in which to create the package\r\n    -h, --help                 Show this message and exit.\r\n\r\n### install\r\n\r\n`docassemblecli3` provides a command-line utility called `install`, which\r\ninstalls a Python package on a remote server using files on your local computer.\r\n\r\nFor example, suppose that you wrote a docassemble extension package called\r\n`docassemble.foobar` using the **docassemble** Playground. In the Playground,\r\nyou can download the package as a ZIP file called `docassemble-foobar.zip`. You\r\ncan then unpack this ZIP file and you will see a directory called\r\n`docassemble-foobar`. Inside of this directory there is a directory called\r\n`docassemble` and package metadata such as `setup.py`, `setup.cfg`, or `pyproject.toml`.\r\n\r\nFrom the command line, use `cd` to navigate into the directory\r\n`docassemble-foobar`. Then run:\r\n\r\n    da install\r\n\r\nor you can specify the directory of the package you want to install (if\r\n`docassemble-foobar` is in your current directory):\r\n\r\n    da install --directory docassemble-foobar\r\n\r\nThe first time you run this command, it will ask you for the URL of your\r\n**docassemble** server and the [API key] of a user with `admin` or `developer`\r\nprivileges.\r\n\r\nIt will look something like this:\r\n\r\n    $ da install --directory docassemble-foobar\r\n    Base URL of your docassemble server (e.g., https://da.example.com): https://da.example.com\r\n    API key of admin or developer user on https://da.example.com: H3PWMKJOIVAXL4PWUJH3HG7EKPFU5GYT\r\n    Testing the URL and API key...\r\n    Success!\r\n    Configuration saved: ~\\.docassemblecli\r\n    [2024-08-16 18:10:18] Installing...\r\n    Server will restart.\r\n    Waiting for package to install...\r\n    Waiting for server...\r\n    [2024-08-16 18:11:43] Installed.\r\n\r\nThe next time you run `da install`, it will not ask you for the URL and API key.\r\n\r\nYou can run `da install --help` to get more information about how `install`\r\nworks:\r\n\r\n    Usage: da install [OPTIONS]\r\n\r\n    Install a docassemble package on a docassemble server.\r\n\r\n    `da install` tries to get API info from the --api option first (if used), then\r\n    from the first server listed in the ~/.docassemblecli file if it exists\r\n    (unless the --config option is used), then it tries to use environmental\r\n    variables, and finally it prompts the user directly.\r\n\r\n    Options:\r\n    -a, --api \u003cURL TEXT\u003e...      URL of the docassemble server and API key of\r\n                                the user (admin or developer)\r\n    -s, --server SERVER          Specify a server from the config file\r\n    -d, --directory PATH         Specify package directory [default: current\r\n                                directory]\r\n    -c, --config PATH            Specify the config file to use or leave it\r\n                                blank to skip using any config file  [default:\r\n                                C:\\Users\\current_user\\.docassemblecli]\r\n    --project-config / --no-project-config\r\n                                Use .docassemblecli from the package directory\r\n                                first, then fall back to the selected config\r\n                                file  [default: project-config]\r\n    -p, --playground (PROJECT)   Install into the default Playground or into the\r\n                                specified Playground project.\r\n    -r, --restart [yes|no|auto]  On package install: yes, force a restart | no,\r\n                                do not restart | auto, only restart if the\r\n                                package has any .py files or if there are\r\n                                dependencies to be installed  [default: auto]\r\n    -h, --help                   Show this message and exit.\r\n\r\nFor example, you might want to pass the URL and API key in the command itself:\r\n\r\n    da install --api https://da.example.com H3PWMKJOIVAXL4PWUJH3HG7EKPFU5GYT --directory docassemble-foobar\r\n\r\nIf you have more than one server, you can utilize one of the `config` tools `add`:\r\n\r\n    da config add\r\n\r\nto add an additional server configuration to store in your `.docassemblecli`\r\nconfig file. Then you can select the server using `--server`:\r\n\r\n    da install --server da.example.com --directory docassemble-foobar\r\n\r\nIf you do not specify a `--server`, the first server indicated in your\r\n`.docassemblecli` file will be used.\r\n\r\nBy default, `install` looks for a `.docassemblecli` file in the package\r\ndirectory first and falls back to `~/.docassemblecli` if none is present. Use\r\n`--no-project-config` if you want to skip the package-local file. The local\r\nfile can define different default server and Playground settings for `install`\r\nand `watch`.\r\n\r\nThe `--restart no` option can be used when your **docassemble** installation\r\nonly uses one server (which is typical) and you are not modifying .py files. In\r\nthis case, it is not necessary for the Python web application to restart after\r\nthe package has been installed. This will cause `da install` to return a few\r\nseconds faster than otherwise.\r\n\r\nThe `--restart yes` option should be used when you want to make sure that\r\n**docassemble** restarts the Python web application after the package is\r\ninstalled. By default, `da install` will avoid restarting the server if the\r\npackage has no module files and all of its dependencies (if any) are installed.\r\n\r\nBy default, `da install` installs a package on the server. If you want to install\r\na package into your Playground, you can use the `--playground` option.\r\n\r\n    da install --playground --directory docassemble-foobar\r\n\r\nIf you want to install into a particular project in your Playground, indicate\r\nthe project after the `--playground` option, for example project \"testing\".\r\n\r\n    da install --playground testing --directory docassemble-foobar\r\n\r\nInstalling into the Playground with `--playground` is faster than installing an\r\nactual Python package because it does not need to run `pip`.\r\n\r\n### download\r\n\r\nUse `download` to fetch an installed package from the server or from a Playground project.\r\n\r\nExamples:\r\n\r\n    da download docassemble.foobar\r\n    da download --playground testing docassemble.foobar\r\n\r\n### uninstall\r\n\r\nUse `uninstall` to remove a package from the server.\r\n\r\nExample:\r\n\r\n    da uninstall docassemble.foobar\r\n\r\nIf your development installation uses more than one server, it is safe to run\r\n`da install --playground` with `--restart no` if you are only changing YAML files,\r\nbecause Playground YAML files are stored in cloud storage and will thus be\r\navailable immediately to all servers.\r\n\r\n### watch\r\n\r\nYou can use `watch` to automatically `install` your docassemble package every\r\ntime a file in your package directory is changed.\r\n\r\nFor example, if you run:\r\n\r\n    da watch --playground testing --directory docassemble-foobar\r\n\r\nThis will monitor the `docassemble-foobar` directory, and if any non-`.py` file\r\nchanges, it will run:\r\n\r\n    da install --playground testing --restart no --directory docassemble-foobar\r\n\r\nIf a `.py` file is changed, however, it will run\r\n\r\n    da install --playground testing --restart yes --directory docassemble-foobar\r\n\r\nWith `da watch --playground` constantly running, soon after you save a YAML file\r\non your local machine, it will very quickly be available for testing on your\r\nserver.\r\n\r\nTo exit `watch`, press **Ctrl + c**.\r\n\r\nYou can run `da watch --help` to get more information about how `watch`\r\nworks:\r\n\r\n    Usage: da watch [OPTIONS]\r\n\r\n    Watch a package directory and `install` any changes. Press Ctrl + c to exit.\r\n\r\n    Options:\r\n    -d, --directory PATH         Specify package directory [default: current\r\n                                directory]\r\n    -c, --config PATH            Specify the config file to use or leave it\r\n                                blank to skip using any config file  [default:\r\n                                C:\\Users\\current_user\\.docassemblecli]\r\n    --project-config / --no-project-config\r\n                                Use .docassemblecli from the package directory\r\n                                first, then fall back to the selected config\r\n                                file  [default: project-config]\r\n    -p, --playground (PROJECT)   Install into the default Playground or into the\r\n                                specified Playground project.\r\n    -a, --api \u003cURL TEXT\u003e...      URL of the docassemble server and API key of\r\n                                the user (admin or developer)\r\n    -s, --server SERVER          Specify a server from the config file\r\n    -r, --restart [yes|no|auto]  On package install: yes, force a restart | no,\r\n                                do not restart | auto, only restart if any .py\r\n                                files were changed  [default: auto]\r\n    -b, --buffer SECONDS         (On server restart only) Set the buffer (wait\r\n                                time) between a file change event and package\r\n                                installation. If you are experiencing multiple\r\n                                installs back-to-back, try increasing this\r\n                                value.  [default: 3]\r\n    -h, --help                   Show this message and exit.\r\n\r\nYour package's `.gitignore` file is also used by `watch` to decide which files\r\nto ignore. If you don't have a `.gitignore` file in your package, then the\r\ndefault `.gitignore` that `create` makes is used instead. You can also add a\r\n`.dawatchignore` file in the package root for watch-only ignore rules\r\nthat you do not want to place in `.gitignore`; it uses the same gitignore-style\r\npatterns. For example, putting `tests/` in `.dawatchignore` will stop\r\ntest files from triggering installs. The `.git/` directory, `.gitignore`, and\r\n`.dawatchignore` are all ignored by `watch` themselves. The following\r\ndirectories are always ignored by `watch`: `.git`, `__pycache__`, `.mypy_cache`,\r\n`.venv`, `.history`, `build`.\r\n\r\nIf you have a `directory` key for the server in your `.docassemblecli` config\r\nfile, it will cause that server to be used if no `server` is provided and the\r\n`directory` matches the `directory` that `watch` was given\r\n[default: current directory]. Additionally, if there is a `playground` key for\r\nthat server, it will be used when using `watch`.\r\n\r\nBy default, `watch` looks for a `.docassemblecli` file in the package\r\ndirectory first and falls back to `~/.docassemblecli` if none is present. Use\r\n`--no-project-config` if you want to skip the package-local file. The local\r\nfile can point `watch` at one server and Playground while `install` uses\r\nanother.\r\n\r\n#### watchdog\r\n\r\nThe `watch` command depends on the\r\n[watchdog](https://pypi.org/project/watchdog/) Python package. This allows\r\n`watch` to work on the following platforms that [watchdog] supports:\r\n\r\n- Linux 2.6 (inotify)\r\n- macOS (FSEvents, kqueue)\r\n- FreeBSD/BSD (kqueue)\r\n- Windows (ReadDirectoryChangesW with I/O completion ports;\r\n  ReadDirectoryChangesW worker threads)\r\n- OS-independent (polling the disk for directory snapshots and comparing them\r\n  periodically; slow and not recommended)\r\n\r\nAn additional note from [watchdog]'s documentation:\r\n\r\nNote that when using watchdog with kqueue (macOS and BSD), you need the number\r\nof file descriptors allowed to be opened by programs running on your system to\r\nbe increased to more than the number of files that you will be monitoring. The\r\neasiest way to do that is to edit your ~/.profile file and add a line similar\r\nto:\r\n\r\n```bash\r\nulimit -n 1024\r\n```\r\n\r\nThis is an inherent problem with kqueue because it uses file descriptors to\r\nmonitor files. That plus the enormous amount of bookkeeping that watchdog needs\r\nto do in order to monitor file descriptors just makes this a painful way to\r\nmonitor files and directories. In essence, kqueue is not a very scalable way to\r\nmonitor a deeply nested directory of files and directories with a large number\r\nof files.\r\n\r\n### config\r\n\r\nThese commands are for managing your saved servers and config file. They are\r\neasy to use and will prompt you as necessary.\r\n\r\n    Usage: da config [OPTIONS] COMMAND [ARGS]...\r\n\r\n    Manage servers in a docassemblecli config file.\r\n\r\n    Options:\r\n    -h, --help  Show this message and exit.\r\n\r\n    Commands:\r\n    add      Add a server to the config file.\r\n    display  List the servers in the config file.\r\n    new      Create a new config file.\r\n    remove   Remove a server from the config file.\r\n    test     Test the URL and API key.\r\n\r\nThe `.docassemblecli` config file can store additional configuration for each server:\r\n\r\n- `directory`: If the current or provided directory matches this then this server will be selected\r\n- `playground`: Default playground project to use if `directory` matches\r\n- `startup`: If set to \"install\", automatically installs package when `watch` starts\r\n\r\nFor example, your `.docassemblecli` file might look like this:\r\n\r\n```yaml\r\n- apiurl: https://da.example.com\r\n  apikey: H3PWMKJOIVAXL4PWUJH3HG7EKPFU5GYT\r\n  name: da.example.com\r\n  playground: testing\r\n  directory: /path/to/docassemble-mypackage\r\n  startup: install\r\n```\r\n\r\nWith this configuration:\r\n- `da watch` in `/path/to/docassemble-mypackage` will automatically use this server\r\n- It will install to the \"testing\" playground project\r\n- It will install the package once when `watch` starts\r\n\r\nFor per-package defaults, a package directory can also contain its own\r\n`.docassemblecli` file. `da install` and `da watch` will use it automatically\r\nunless you pass `--no-project-config`.\r\n\r\nFor example:\r\n\r\n```yaml\r\nservers:\r\n    - name: dev.example.com\r\n        apiurl: https://dev.example.com\r\n        apikey: DEVKEY\r\n    - name: prod.example.com\r\n        apiurl: https://prod.example.com\r\n        apikey: PRODKEY\r\n\r\nwatch:\r\n    server: dev.example.com\r\n    playground: testing\r\n    startup: install\r\n\r\ninstall:\r\n    server: prod.example.com\r\n    playground: release\r\n```\r\n\r\nWith this configuration:\r\n- `da watch` uses `dev.example.com` and the `testing` Playground\r\n- `da install` uses `prod.example.com` and the `release` Playground\r\n- If the local file is missing, both commands fall back to `~/.docassemblecli`\r\n- `--no-project-config` disables the local file for a command\r\n\r\n## How it works\r\n\r\nThe `install` command is just a simple Python script that creates a ZIP file and\r\nuploads it through the **docassemble** API. Feel free to copy the code and write\r\nyour own scripts to save yourself time. (That's how this version started!)\r\n\r\n## Contributing\r\n\r\nPull requests are welcome. For major changes, please open an issue first\r\nto discuss what you would like to change.\r\n\r\nPlease make sure to update tests as appropriate.\r\n\r\n## License\r\n\r\n[MIT](https://choosealicense.com/licenses/mit/)\r\n\r\n[docassemble]: https://docassemble.org\r\n[docassemblecli]: https://github.com/jhpyle/docassemblecli/\r\n[API key]: https://docassemble.org/docs/api.html#manage_api\r\n[watchdog]: https://pypi.org/project/watchdog/\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpagh%2Fdocassemblecli3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjpagh%2Fdocassemblecli3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpagh%2Fdocassemblecli3/lists"}