diff --git a/README.md b/README.md index d2f7fb065..f4649c935 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,24 @@ [![PyPI version fury.io](https://badge.fury.io/py/dandi.svg)](https://pypi.python.org/pypi/dandi/) [![Documentation Status](https://readthedocs.org/projects/dandi/badge/?version=latest)](https://dandi.readthedocs.io/en/latest/?badge=latest) -This project is under heavy development. Beware of [hidden](I-wish-we-knew) and -[disclosed](https://github.com/dandi/dandi-cli/issues) issues, or +The [DANDI Python client](https://pypi.org/project/dandi/) allows you to: + +* Download `Dandisets` and individual subject folders or files +* Validate data to locally conform to standards +* Organize your data locally before upload +* Upload `Dandisets` +* Interact with the DANDI archive's web API from Python +* Delete data in the DANDI archive +* Perform other auxiliary operations with data or the DANDI archive + +**Note**: This project is under heavy development. See [the issues log](https://github.com/dandi/dandi-cli/issues) or [Work-in-Progress (WiP)](https://github.com/dandi/dandi-cli/pulls). ## Installation -At the moment DANDI client releases are [available from PyPI](https://pypi.org/project/dandi) -and [conda-forge](https://anaconda.org/conda-forge/dandi). You could -install them in your Python (native, virtualenv, or conda) environment via +DANDI Client releases are [available from PyPI](https://pypi.org/project/dandi) +and [conda-forge](https://anaconda.org/conda-forge/dandi). Install them in your Python (native, virtualenv, or +conda) environment via pip install dandi @@ -22,13 +31,11 @@ or conda install -c conda-forge dandi -if you are in a conda environment. -## dandi tool +## CLI Tool -This package provides a `dandi` command line utility with a basic interface -which should assist you in preparing and uploading your data to and/or obtaining -data from the http://dandiarchive.org: +This package provides a command line utility with a basic interface +to help you prepare and upload your data to, or obtain data from, the [DANDI archive](http://dandiarchive.org): ```bash $> dandi @@ -45,51 +52,85 @@ Usage: dandi [OPTIONS] COMMAND [ARGS]... Options: --version - -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL] - Log level name [default: INFO] + -l, --log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL] + Log level (case insensitive). May be + specified as an integer. [default: INFO] --pdb Fall into pdb if errors out --help Show this message and exit. Commands: - download Download a file or entire folder from DANDI - ls List .nwb files and dandisets metadata. - organize (Re)organize files according to the metadata. - register Register a new dandiset in the DANDI archive - upload Upload dandiset (files) to DANDI archive. - validate Validate files for NWB (and DANDI) compliance. + delete Delete dandisets and assets from the server. + digest Calculate file digests + download Download a file or entire folder from DANDI. + instances List known Dandi Archive instances that the CLI can... + ls List .nwb files and dandisets metadata. + move Move or rename assets in a local Dandiset and/or on... + organize (Re)organize files according to the metadata. + service-scripts Various utility operations + shell-completion Emit shell script for enabling command completion. + upload Upload Dandiset files to DANDI Archive. + validate Validate files for NWB and DANDI compliance. + validate-bids Validate BIDS paths. ``` -Each of the commands has a set of options to alter their behavior. Please run -`dandi COMMAND --help` to get more information, e.g. +Each of the commands has a set of options to alter its behavior. Run +`dandi COMMAND --help` to get more information: ``` $> dandi ls --help -Usage: dandi ls [OPTIONS] [PATHS]... - - List .nwb files metadata +Usage: dandi ls [OPTIONS] PATH|URL + + List .nwb files and dandisets metadata. + + The arguments may be either resource identifiers or paths to local + files/directories. + + Accepted resource identifier patterns: + - DANDI:[/] + - https://dandiarchive.org/... + - https://identifiers.org/DANDI:[/] ( cannot be 'draft') + - https://[/api]/[#/]dandiset/[/][/files[?location=]] + - https://*dandiarchive-org.netflify.app/... + - https://[/api]/dandisets/[/versions[/]] + - https://[/api]/assets/[/download] + - https://[/api]/dandisets//versions//assets/[/download] + - https://[/api]/dandisets//versions//assets/?path= + - dandi:///[@][/] + - https:///... Options: -F, --fields TEXT Comma-separated list of fields to display. An empty value to trigger a list of available fields to be printed out - -f, --format [auto|pyout|json|json_pp|yaml] + -f, --format [auto|pyout|json|json_pp|json_lines|yaml] Choose the format/frontend for output. If 'auto', 'pyout' will be used in case of multiple files, and 'yaml' for a single file. + -r, --recursive Recurse into content of + dandisets/directories. Only .nwb files will + be considered. + -J, --jobs INTEGER Number of parallel download jobs. [default: + 6] + --metadata [api|all|assets] + --schema VERSION Convert metadata to new schema version --help Show this message and exit. ``` -See [DANDI Handbook](https://www.dandiarchive.org/handbook/10_using_dandi/) -for examples on how to use this client in various use cases. -## Development/contributing +## Third-party Components -Please see [DEVELOPMENT.md](./DEVELOPMENT.md) file. +**dandi/tests/skip.py** -- from https://github.com/ReproNim/reproman, as of v0.2.1-40-gf4f026d +Copyright (c) 2016-2020 ReproMan Team -## 3rd party components included +## Resources -### dandi/tests/skip.py +* To learn how to interact with the DANDI archive and for examples on how to use the DANDI Client in various use cases, +see [the handbook](https://www.dandiarchive.org/handbook/). -From https://github.com/ReproNim/reproman, as of v0.2.1-40-gf4f026d -Copyright (c) 2016-2020 ReproMan Team +* To get help: + - ask a question: https://github.com/dandi/helpdesk/discussions + - file a feature request or bug report: https://github.com/dandi/helpdesk/issues/new/choose + - contact the DANDI team: help@dandiarchive.org + +* To understand how to contribute to the dandi-cli repository, see the [DEVELOPMENT.md](./DEVELOPMENT.md) file.