Setting Up the CLI

Setting Up the CLI#

This is an optional step. You can use the CLI to interact with Materials Commons and perform many common tasks such as creating projects, uploading/downloading files, or creating directories on the server.

Installing the CLI#

  1. Install the Materials Commons CLI:

    1. Install the CLI locally to your user account (recommended):

      pip install --user materials-commons-cli

    Note

    When installed locally make sure to add the installation directory to your path:

    export PATH="$PATH:$(python3 -m site --user-base)/bin"

    1. Install the CLI globally:

      sudo pip install materials-commons-cli

Adding Your API Key#

The Materials Commons CLI requires authentication through an API key to interact with a Materials Commons instance (called a “remote”). This guide explains how to configure your CLI access.

Configuration Steps#

  1. Configure Remote Instance

    Set up the CLI to connect to a specific Materials Commons server (e.g., materialscommons.org)

    mc remote –add <email> https://materialscommons.org/api

  2. Set Default Remote

    Establish your primary Materials Commons instance for CLI operations

    mc remote –set-default <email> https://materialscommons.org/api

Note

You will be prompted for your password to retrieve and save your API key locally.

Connecting to your project#

This step assumes you’ve organized your files under a root project directory.

Before starting your project setup, we recommend reviewing the best practices guide for optimal file organization.

Important

When using the Materials Commons CLI, all project files must reside in a single root directory. This directory serves as the base location that will be linked to your Materials Commons project.

We are going to connect to the project you created in Your First Project.

Use the mc clone command to create a local copy of your existing Materials Commons project.

Important

The cloned project directory will appear empty initially. Files from the remote project are not automatically downloaded - they must be explicitly requested through download commands.

  1. Create and navigate to a new directory:

    mkdir <project-name>
cd <project-name>

  2. List available projects:

    All existing Materials Commons projects you have access to can be listed using mc proj:

    $ mc proj
    name                       owner                  id    updated_at
--  -------------------------  ---------------------  ----  --------------------
    Mg-Nd CASM project         adam@email.com         33    2020 Oct 16 17:40:12
    Mg-Y CASM project          adam@email.com         39    2020 Oct 16 17:40:12

  3. Clone the desired project:

    mc clone <project-id>

Note

The project ID can be found in the ‘id’ column of the mc proj output.

Contents