> For the complete documentation index, see [llms.txt](https://icij.gitbook.io/datashare/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://icij.gitbook.io/datashare/concepts/cli-reference.md). # CLI reference Complete reference of Datashare's command-line interface subcommands and global flags. Datashare's command-line interface is organized as subcommands. Run `datashare --help` for an overview, or `datashare COMMAND --help` for help on a specific subcommand. Running `datashare` with no arguments is equivalent to `datashare app start` — it starts the web application in the default mode. ## Subcommands | Subcommand | Description | | ------------------------ | ------------------------------------------------------------------------ | | `app start` | Start the Datashare web application server | | `stage run` | Run one or more document processing pipeline stages | | `worker run` | Start an async task worker daemon | | `plugin list` | List available plugins | | `plugin install ` | Install a plugin by id, URL, or file path | | `plugin delete ` | Remove an installed plugin | | `extension list` | List available extensions | | `extension install ` | Install an extension by id, URL, or file path | | `extension delete ` | Remove an installed extension | | `api-key get` | Get the current user's API key | | `api-key create` | Create an API key | | `api-key delete` | Delete an API key | | `user create` | Create a Datashare user | | `user delete` | Delete a Datashare user and all their owned data | | `project create` | Create a Datashare project | | `project delete` | Delete a Datashare project (DB, ES index, queues, report map, artifacts) | | `project grant` | Grant a role to a user on a project (replaces any existing role) | | `project revoke` | Revoke all project roles for a user | ## `app start` Start the Datashare web application. The default mode is `LOCAL` (single-user, embedded services). Running `datashare` with no arguments is a shorthand for `datashare app start`. ```bash # Local mode (default) datashare app start # Server mode datashare app start --mode SERVER \ --elasticsearchAddress http://elasticsearch:9200 \ --redisAddress redis://redis:6379 # Embedded mode (all services in one JVM) datashare app start --mode EMBEDDED ``` ## `stage run` Run one or more document processing [stages](/datashare/concepts/cli-stages.md). Requires `--stages`. ```bash # Scan and index documents datashare stage run --stages SCAN,INDEX \ --dataDir /path/to/documents \ --elasticsearchAddress http://elasticsearch:9200 # Extract named entities datashare stage run --stages NLP \ --nlpPipeline CORENLP \ --elasticsearchAddress http://elasticsearch:9200 # Full pipeline datashare stage run --stages SCAN,INDEX,NLP \ --dataDir /path/to/documents \ --elasticsearchAddress http://elasticsearch:9200 ``` The options most often used with this subcommand: | Flag | Default | Description | | -------------------- | ---------- | ---------------------------------------------------------------------------------- | | `--stages` | required | Comma-separated stages to run | | `--reportName` | none | Report map recording the outcome of each file, required for resumable runs | | `-o, --ocr` | `true` | Enable OCR on images | | `--ocrLanguage` | `eng` | Tesseract languages, for example `eng+fra` | | `--ocrStrategy` | `NO_OCR` | PDF OCR strategy (`NO_OCR`, `AUTO`, `OCR_AND_TEXT_EXTRACTION`, `OCR_ONLY`) | | `--ocrTimeout` | `12h` | Timeout for a single OCR run | | `--parseTimeout` | `24h` | Timeout for parsing one document, `0` disables it | | `--parallelism` | CPU cores | Documents extracted concurrently | | `--maxContentLength` | `20000000` | Maximum extracted text kept per document | | `--maxEmbedDepth` | `20` | Maximum nesting depth of embedded documents | | `--nlpPipeline` | `CORENLP` | NER engine (`CORENLP`, `OPENNLP`, `EMAIL`, `SPACY`) | | `--searchQuery` | none | Restricts `ENQUEUEIDX`, in Datashare query syntax or as a raw Elasticsearch clause | | `--artifactDir` | none | Directory for the embedded document cache, required by `ARTIFACT` | The complete list, with the environment variables and settings-file keys that have no flag, is in [Indexing options](/datashare/server-mode/indexing/options.md). ## `worker run` Start an async task worker that processes background tasks (batch searches, batch downloads, indexing, NER extraction). ```bash datashare worker run \ --redisAddress redis://redis:6379 \ --busType REDIS ``` ## `plugin` and `extension` ```bash # List available plugins datashare plugin list # Install a plugin datashare plugin install datashare-plugin-ner-corenlp # Remove a plugin datashare plugin delete datashare-plugin-ner-corenlp # List available extensions datashare extension list # Install an extension datashare extension install datashare-extension-nlp-opennlp # Remove an extension datashare extension delete datashare-extension-nlp-opennlp ``` ## `user` Create and delete Datashare users. See [Manage users from the CLI](/datashare/server-mode/manage-users-from-the-cli.md) for details. ```bash # Create a user datashare user create alice --email alice@example.org # Create a user with a password and project access datashare user create alice --email alice@example.org --password $PW --groups p1,p2 # Delete a user and all their owned data datashare user delete alice --yes ``` ## `project` Create and delete projects, and manage project permissions. See [Manage projects from the CLI](/datashare/server-mode/manage-projects-from-the-cli.md) for details. ```bash # Create a project datashare project create my-project --label 'My Project' # Delete a project (DB, ES index, queues, report map, artifacts) datashare project delete my-project --yes # Grant a role to a user (admin, editor, member or visitor) datashare project grant my-project alice admin # Revoke all project roles for a user datashare project revoke my-project alice ``` All `user` and `project` subcommands accept `--json` (machine-readable output), `--no-input` (disable prompts) and idempotency flags (`--if-not-exists` / `--if-exists`) for scripting. ## Global flags These flags can be placed before any subcommand and apply to all subcommands. | Flag | Default | Description | | ------------------------ | ----------------------------------------------------------- | --------------------------------------------------------------- | | `-d, --dataDir` | `~/Datashare` | Document source directory | | `-P, --defaultProject` | `local-datashare` | Default project name, also the Elasticsearch index name | | `-s, --settings` | `$DATASHARE_HOME/dist/datashare.conf` (set by the launcher) | Path to settings file | | `--logLevel` | `INFO` | Log level (`DEBUG`, `INFO`, `WARN`, `ERROR`) | | `--charset` | JVM default | Output encoding for extracted text and metadata | | `-l, --language` | detected | Force the language of indexed documents instead of detecting it | | `--digestAlgorithm` | `SHA384` | Hash used to compute document ids | | `--digestProjectName` | none | Include the project name in the document hash | | `--elasticsearchAddress` | `http://elasticsearch:9200` | Elasticsearch URL | | `--redisAddress` | `redis://redis:6379` | Redis URL | | `--messageBusAddress` | `redis://redis:6379` | Data bus URL | | `--dataSourceUrl` | local SQLite file | JDBC URL of the database | | `--busType` | `MEMORY` | Data bus type (`MEMORY`, `REDIS`, `AMQP`) | | `--queueType` | `MEMORY` | Queue type (`MEMORY`, `REDIS`, `AMQP`) | | `--queueName` | `extract:queue` | Base queue name, each stage reads `:` | | `--queueCapacity` | `1000000` | Maximum entries held in an in-memory queue | | `--no-color` | none | Disable colored output | | `-h, --help` | none | Show help and exit | | `-V, --version` | none | Print version and exit | Global flags are position-independent: they can appear before or after the subcommand name. ## Backward compatibility The legacy flag-based syntax (`--mode`, `--stage`, `-m CLI`, etc.) is still accepted for backward compatibility. New scripts should use the subcommand syntax. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://icij.gitbook.io/datashare/concepts/cli-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.