Metadata-Version: 2.4
Name: vswmc-cli
Version: 2.2.1.dev357
Summary: VSWMC Command-Line Tools
Home-page: https://spaceweather.hpc.kuleuven.be
Author: Rays of Space
Author-email: info@raysofspace.com
License: LGPL
Platform: Posix; MacOS X; Windows
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: six
Requires-Dist: requests
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: platform
Dynamic: requires-dist
Dynamic: summary

# VSWMC Command-Line Interface

Install with pip:

    pip install --upgrade vswmc-cli

This will install a `vswmc` command on your system. The `vswmc` command uses an S2P OAuth access token for authentication. Obtain the token outside the CLI, for example with the OAuth 2.0 Client Credentials flow described in the SSO migration guide, then provide it with one of:

`VSWMC_ACCESS_TOKEN`

&nbsp;&nbsp;&nbsp; Read the access token from the environment.

`--token TOKEN`

&nbsp;&nbsp;&nbsp; Read the access token from the command line.

`--token-file FILE`

&nbsp;&nbsp;&nbsp; Read the access token from a file.

Example token request:

    curl \
      -d 'client_id=<M2M_CLIENT_ID>' \
      -d 'client_secret=<M2M_CLIENT_SECRET>' \
      -d 'grant_type=client_credentials' \
      -d 'scope=<VSWMC_RESOURCE_SERVER_CLIENT_ID>' \
      'https://sso.s2p.esa.int/realms/swe/protocol/openid-connect/token'

Example CLI usage:

    export VSWMC_ACCESS_TOKEN=<ACCESS_TOKEN>
    vswmc simulations list

## List available simulations
    vswmc simulations list

This shows the parameters that a run requires.


## Start a run
    vswmc run [--param-file PARAM_FILE] [--param PARAM=VALUE ...] -- SIMULATION

This command returns the ID of the new run via stdout. You can use this ID to fetch the log or fetch result files.

OPTIONS
<dl>
<dt><tt>--param-file PARAM_FILE</tt></dt>
<dd>Read parameters from a file.</dd>
<dt><tt>--param PARAM=VALUE ...</tt></dt>
<dd>Set parameters.</dd>
</dl>

Each simulation supports different parameters. To know what parameters you need for a particular simulation, run:

    vswmc simulations describe SIMULATION


## List runs
    vswmc ps [--simulation SIMULATION] [-a, --all]

OPTIONS
<dl>
<dt><tt>--simulation SIMULATION</tt></dt>
<dd>Filter on simulation.</dd>
<dt><tt>-a, --all</tt></dt>
<dd>List all runs (default shows only ongoing)</dd>
</dl>


## Copy a result file to disk
    vswmc cp SRC DST

Downloads a remote result file to local disk. The source should be specified in the format <tt>RUN:FILE</tt>. The <tt>DST</tt> argument can be a local file or directory.


## Fetch the logs of a run
    vswmc logs RUN


## List the results of a run
    vswmc ls [-l] RUN

OPTIONS
<dl>
<dt><tt>-l</tt></dt>
<dd>Print long listing</dd>
</dl>


## Save all results of a run
    vswmc save RUN

Saves all result files of a run. The results of each individual task in this run are compressed and saved into a zip archive named after the model for that task.


## Stop one or more runs
    vswmc stop RUN ...


## Remove one or more runs
    vswmc rm RUN ...


## Create a product
    vswmc products create [--metadata-file FILE] [--metadata PARAM=VALUE ...] [--attach FILE ...] -- PRODUCT_TYPE

OPTIONS
<dl>
<dt><tt>--param-file PARAM_FILE</tt></dt>
<dd>Read parameters from a file.</dd>
<dt><tt>--param PARAM=VALUE ...</tt></dt>
<dd>Set parameters.</dd>
<dt><tt>--attach FILE ...</tt></dt>
<dd>Attach product files</dd>
</dl>

EXAMPLE

    vswmc products create --metadata test=123 --attach ../testdata/solar_wind_boundary.dat -- MHD0.1-1

Returns the ID of the created product.


## Start a run using a product as input

    vswmc run --param corona=6273ce7678eeb43c60d2eb8f \
              --param grid=test_light \
              --param cmes=examples/resources/cme_list.dat \
              -- euhforia-heliosphere-standalone

The `corona` parameter expects a product identifier.
