============ Command-Line ============ High-level components of the functionality described in the `Usage <./usage.html>`_ section are also accessible via the ``esp`` command-line entry point. Using the entry point, you can import workflows/protocols, seed ESP with new data, create samples, and update metadata for entries in the ESP database. .. TODO: INCLUDE HIGH-LEVEL HELP DOCUMENTATION FROM COMMAND Status ------ To check the status of a running ESP instance, you can use the ``status`` entry point: .. code-block:: bash ~$ python -m esp status Connecting to esp with following credentials: host: localhost port: 8002 email: admin@localhost cookies: None Connection established! Import ------ As mentioned in the `Usage <./usage.html>`_ section of the documentation, you can import YAML configuration for each model defined in the python client. Below is an example of how to import a ``Workflow`` via the command-line (see the `Usage <./usage.html>`_ section for an example of the config file format: .. code-block:: bash ~$ python -m esp import workflow /path/to/workflow.yml You can also use the same entry point for importing experiment data into the ESP application. Here's an example config definition for a project and related experiments (with data): .. code-block:: yaml Miseq Sequencing: desc: Project container for MiSeq runs. tags: - illumina - miseq experiments: - MS001: submit: true workflow: Illumina Sequencing tags: - illumina - miseq samples: - ESP000001 - ESP000002 protocols: - Set Samples: complete: true data: Note: Ready to go! - Create Illumina Library: complete: true cols: - Index Type - I7 Index ID - I5 Index ID data: - ['Nextera DNA', 'N701', 'N501'] - ['Nextera DNA', 'N702', 'N502'] - Analyze Sequencing Results: run: true complete: true data: - ESP000001: Reference: GRCh38 - ESP000002: Reference: GRCh37 - MS002: submit: false workflow: Illumina Sequencing tags: - illumina - miseq samples: - ESP000001 To import this project, you can use an entry-point call with the same flavor: .. code-block:: bash ~$ esp import project /path/to/project.yml This will import the entire Project with related Experiment, Sample, and SampleSheet objects. For more information on the ``import`` entry point, you can use the ``-h`` flag: .. code-block:: bash ~$ python -m esp import -h Seed ---- To do a bulk import, you can use the `seed` entry point: .. code-block:: bash ~$ python -m esp seed /path/to/content.yml For this type of import, all of your content can be defined in the same file if the models are explicitly declared: .. code-block:: yaml --- - model: workflow data: My Workflow: desc: Definition for workflow. ... - model: sample_type data: /path/to/sample_type.yml - model: user data: ${CWD}/users.yml Any type of importable model from the client can be included in this config. To see the list of models supported by the client, use the ``python -m esp import -h`` command. Watch ----- During development, it's useful to have real-time updates of changes you make to content config files. This is possible with the `watch` entrypoint. To use the `watch` entrypoint, include `watch` before your `seed` or `import` command: .. code-block:: bash ~$ # with seed ~$ python -m esp watch seed /path/to/content.yml ~$ # with import ~$ python -m esp watch import workflow /path/to/workflow.yml This will monitor the directory containing that seed file for changes and will run the command any time a change occurs. Notably, this helps shorten the develop/test cycle for content in the SDK, where `make import` isn't necessary to re-seed an instance with content. With this the `watch` entrypoint will watch for changes made by developers and update their esp instance in real-time. You can also include additional directories into the search path for the `watch` entrypoint. For example, to watch a content directory in the SDK and run `seed` each time a change is made in that directory, you can use: .. code-block:: bash ~$ python -m esp watch --include=./content seed ./roles/content.yml This makes the process of iterating on multi-part configuration for an instance more manageable (especially since you can comment out items in the seed file to cut down on imports during development/testing). Export ------ Along with imports, you can also export specific data. To export individual models, you can use: .. code-block:: bash ~$ esp export workflow 'Illumina Sequencing' > Illumina-Sequencing.yml Similarly, to export all data for a project, use: .. code-block:: bash ~$ esp export project -n 'My Project' > My-Project.yml For more information on the ``export`` entry point, you can use the ``-h`` flag: .. code-block:: bash ~$ python -m esp export -h .. note:: Exported files won't contain any information about UUIDs created in the system. Only information that can be used to seed the system from scratch will be exported. This is intentional and meant to not keep unnecessary history from propagating across installs. For a full export, use the export utilities from within the application. Dump ---- Along with exporting a specific model, you can also do a full dump (export) of all content models in your instance. For example, if you use the client to run: .. code-block:: bash ~$ esp dump You will find a folder called ``content/`` in your current directory with content models organized like the following: .. code-block:: text . ├── chains │   └── Whole-Genome-Sequencing.yml ├── files │   ├── Spectramax_Template_field_descriptions.pdf │   └── pn_010156.pdf ├── inventory │   ├── Item-Types.yml │   └── Sample-Types.yml ├── pipelines │   ├── ABI-Zip-Process.yml │   ├── Generate-NovaSeq-Runsheet.yml ├── reports │   ├── flow_cell_layout.html │   ├── held_samples.html ├── tasks │   └── import_nanodrop.py └── workflows ├── Bioanalyzer.yml ├── DNA-Isolation.yml ├── DNA-Quantification.yml ├── Library-Prep.yml ├── Whole-Genome-Bioinformatics.yml This process will also create a ``seed`` file (see above) with a manifest of content definitions in ``content/seed/content.yml``. You can change the default seed file location using the ``--seed`` argument. The root folder for the content dump can be set with the ``-r`` argument. Similarly, you can dump all content for a specific model using the ``--model`` command-line argument: .. code-block:: bash ~$ esp dump --model SampleType For more specific information on the ``dump`` entry point, you can use the ``-h`` flag: .. code-block:: bash ~$ python -m esp dump -h