ARC Commander QuickStart

This guide introduces the ARC Commander, a command line tool to create, edit and share you ARC. It requires some experience with the command line (command prompt, shell, terminal,…).

Tip

Before following this guide, we recommend to explore the Getting Started guide for a more comprehensive overview of ARC concepts and features.

Here we reproduce parts of Viola’s example ARC created there. However, the ARC Commander by design does not offer all functions you know from ARCitect. For metadata annotations you can either work on your ARC in ARCitect as explained in the Getting Started guide or explore the different options of using Swate.

Setup

Section titled Setup

Before using the ARC commander, please install Git, Git-LFS and ARC Commander and setup access to your DataHUB account.

1. Install and setup Git and Git-LFS

   Before using ARCitect (except for Windows) or ARC Commander, Git and Git LFS must be installed.

   Download and install Git and Git LFS

   Section titled Download and install Git and Git LFS

   Windows

   1. Download the Git installer for Windows from https://git-scm.com.
   2. Open the installer and follow the installation instructions
   3. During the installation, make sure to include Git LFS (Large File Support)

   Macos

   1. Open a Terminal

   2. (Optional, if homebrew is not yet installed:) Install the package manager homebrew via

      /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

   3. Install Git via homebrew with

      brew install git

   4. Install Git LFS via homebrew with

      brew install git-lfs

   5. Initialize Git LFS via

      git lfs install

   Linux

   1. Open a Terminal

   2. Update the package manager apt via

      sudo apt update

   3. Install Git via apt with

      sudo apt-get install git

   4. Install Git LFS via apt with

      sudo apt-get install git-lfs

   5. Initialize Git LFS via

      git lfs install

   Tip

   For more details or alternatives, check out the documentation of Git and Git LFS.

   Check your Git installation

   Section titled Check your Git installation

   To check, that Git and Git LFS are installed on your computer, open a new command prompt or terminal and execute the following two commands. These should display the installed version. If not, follow the installation instructions.

   1. Open a command prompt or terminal

   2. Check the installed Git version via

      git --version

      Tip

      Recommended Git version ≥ 2.32.0

   3. Check the installed Git LFS version via

      git-lfs --version

      Tip

      Recommended Git LFS version ≥ 3.7.0

   Configure Git User

   Section titled Configure Git User

   Git always signs “commits” with a user name and e-mail address. These are then also used by the DataHUB to associate the commits to your user account.

   To add your user name and email address to the git configuration on your computer, run the following two commands in a command prompt or terminal. Make sure to replace “Your DataHUB Name” and “Your DataHUB Email Address” with your information from the DataHUB.

   1. Your name

   git config --global user.name "Your DataHUB Name"

   2. Your email address

   git config --global user.email "Your DataHUB Email Address"

   Tip

   Configuration needs to be done only once after installation of git on your system.

   Check your Git configuration

   Section titled Check your Git configuration

   Run this command to display your user configuration

   git config --global --get-regexp user

   Enable Git to store credentials on your computer

   Section titled Enable Git to store credentials on your computer

   To avoid having to type in your DataHUB credentials, you can enable to store the information (e.g. a DataHUB password or token) on your computer. This leverages the password manager of you operating system.

   Windows

   1. Open a command prompt or powershell

   2. Execute the following command

      git config --global credential.helper store

   Macos

   1. Open a terminal

   2. Execute the following command

      git config --global credential.helper osxkeychain

   Linux

   1. Open a terminal

   2. Execute the following command

      git config --global credential.helper store

2. Install ARC Commander

   Head to the ARC Commander’s GitHub release page. Download the newest release for your operating system (OS) and follow the instructions for your OS listed below.

   Windows

   Head to the ARC Commander’s GitHub release page. Download the newest release for Windows.

   1. In Windows Explorer, head over to the folder where you downloaded the ARC Commander, e.g.

   2. You can move the .exe to a desired folder, e.g. to your personal folder

   3. Add the folder with the ARC Commander to your PATH:

      • Open the Start Menu, type in path and click on Edit the system environment variables
      • Click on Environment Variables…, click on Path and on Edit… in the tab User variables for <your username>, click on New and type in the full path to your folder as seen in the example below:
      • This allows you to start the ARC Commander from any folder
      • Please make sure that you do not have any blank spaces in your path

      Tip

      If you do not have admin rights on the computer, please open the settings “Edit environment variables for your account” (see screen shot above) and follow the same steps.

   4. Navigate to a folder in which you want to initialize an ARC

   5. Open the Command Prompt (CMD) via typing in cmd in the folder address, press Enter

   6. Run the ARC Commander from the CMD by executing arc

      Tip

      A global config file will be created the first time you use the ARC Commander in the (hidden) folder <YourDrive>:\Users\<Username>\AppData\Roaming\DataPLANT\ArcCommander\

   7. Done! 🎉

   Macos

   1. Open a Terminal (Applications -> Utilities -> Terminal)

   2. Copy/paste the following commands into your terminal and execute them to (a) download the latest ARC Commander release, (b) change permissions to make the ARC Commander executable and (c) move the ARC Commander program to a location from where it is executable via the terminal:

      First, you need to verify if your machine is using an AMD / x86 processor or ARM processor.

      uname -m

      This command will return the processor type. If it returns x86_64 , your system is x86. If it returns arm64 , armv7l , or similar, it is ARM.

      For AMD / x86 processors

      curl -LO https://github.com/nfdi4plants/ARCCommander/releases/download/v1.0.2/arc_osx-x64
      chmod a+x ./arc_osx-x64
      mv ./arc_osx-x64 /usr/local/bin/arc

      For ARM processors

      curl -LO https://github.com/nfdi4plants/ARCCommander/releases/download/v1.0.2/arc_osx-arm64
      chmod a+x ./arc_osx-arm64
      mv ./arc_osx-arm64 /usr/local/bin/arc

      Caution

      By moving the ARC commander binary to /usr/local/bin/ it also becomes available to other users on your machine.

   3. Run ARC Commander from the terminal by executing:

      arc

   4. MacOS security note: On first execution, MacOS will not allow arc to be run. Instead it opens a pop-up:

      > "arc" cannot be opened because it is from an unidentified developer

   5. Open the Security Panel in system Preferences (Applications -> System Preferences -> “Security & Privacy”) or by executing the following command in your terminal:

      open "x-apple.systempreferences:com.apple.preference.security"

      In the “General” tab click the bottom-right button “Allow Anyway” right next to

      > arc was blocked from use because it is not from an identified developer.

   6. Head back to the terminal and execute arc again. Another pop-up will ask you to confirm by clicking “Open”.

   7. Check that arc is properly installed by executing

      arc --version

      You should see the following or similar message:

      > Start processing parameterless command.
      > Start Arc Version
      > v1.0.0
      > Done processing command.

      Tip

      A global config file will be created the first time you use the ARC Commander at ~/.config/DataPLANT/ArcCommander/ArcCommander.config

   Linux

   1. Download the latest ARC Commander release

      wget https://github.com/nfdi4plants/ARCCommander/releases/download/v1.0.0/arc_linux-x64

   2. Make it executable

      chmod u+x arc_linux-x64

   3. Move to suitable place (e.g. in your home directory or to /home/bin/ to make it accessible for all users)

      if ! [ -d "$HOME/bin" ]; then mkdir "$HOME/bin"; fi # If it does not exist, create a folder `bin` in your home directory.
      mv arc_linux-x64 $HOME/bin/arc # move executable to that folder

   4. You might have to start a fresh terminal or source ~/.profile

   5. Test that ARC Commander is properly installed

      arc --version

      You should see the following or similar message:

      > Start processing parameterless command.
      > Start Arc Version
      > v1.0.0
      > Done processing command.

      Tip

      A global config file will be created the first time you use the ARC Commander at ~/.config/DataPLANT/ArcCommander/ArcCommander.config

3. Register for a DataPLANT account

   With a DataPLANT account you can use the DataHUB and share your ARC for collaboration.

   Registration

   Section titled Registration

   Please register here.

   

   DataPLANT roles

   Section titled DataPLANT roles

   During the registration you can “Choose your role in DataPLANT”:

   • DataSteward
     • Member of / associated to DataPLANT
     • Teaches DataPLANT tools and services to community members
   • Developer
     • Member of / associated to DataPLANT
     • Develops DataPLANT tools and services
   • Member
     • Other member of DataPLANT
   • User
     • User who want to use the DataPLANT tools and services

   

   DataPLANT account settings

   Section titled DataPLANT account settings

   If you want to adjust your account settings, simply click the login icon in the navigation bar on this site.

   • In the tab “Password” you can modify your password.
   • In the tab “Authenticator” you can set up Two Factor Authentication (2FA).
4. Setup DataHUB access

   The DataHUB allows you to share your ARCs with registered lab or project partners. After registration, you need to setup the ARC Commander for smooth ARC synchronization between your computer and the DataHUB.

   Tip

   This needs to be done only once per computer.

   Enable Git to store credentials on your computer

   Section titled Enable Git to store credentials on your computer

   To avoid having to type in your DataHUB credentials, you can enable to store the information (e.g. a DataHUB password or token) on your computer. This leverages the password manager of you operating system.

   Windows

   1. Open a command prompt or powershell

   2. Execute the following command

      git config --global credential.helper store

   Macos

   1. Open a terminal

   2. Execute the following command

      git config --global credential.helper osxkeychain

   Linux

   1. Open a terminal

   2. Execute the following command

      git config --global credential.helper store

   Receive and store a DataHUB access token

   Section titled Receive and store a DataHUB access token

   arc remote accesstoken get -s https://git.nfdi4plants.org

   A browser window will open asking for your DataPLANT login. After login you are asked to authorize your computer to communicate with the DataHUB. In case you are already logged in, the browser will directly display a plain Success message to you.

   Tip

   This authenticates your computer to communicate with your personal DataHUB account

   Tip

   After two hours you have to repeat this process as this token will expire. Have a look at the next section to learn how to create a longer lasting token (e.g. for large data uploads).

   Store a configurable DataHUB access token for your project

   Section titled Store a configurable DataHUB access token for your project

   Access tokens created with the ARCommander expire after two hours. To create a longer-lasting access token for your project, follow these steps:

   1. Create a project access token

      Note

      This guide shows you how to generate a Project Access Token.
      Project Access Tokens are scoped to a single ARC and cannot be used for other ARCs.

      1. Sign in to the DataHUB

      2. Open your Project (ARC)

      3. Navigate to the ARC’s settings

      4. Open the Access Tokens settings in the sidebar (1)

      5. Enter or adapt the required token information (2) (more about token information here)

      6. Click Create project access token (3)

         

      7. Your new project access token appears on top. Copy (4) and use it in the desired application.

         

   2. Store the token in your local ARC

      arc remoteaccess accesstoken store --token <replaceWithYourToken>

   Once set up, you will not need to authenticate yourself (e.g., by manually retrieving a token through ‘arc remote token get’) until the token expires. When switching to another machine you have to repeat the process.

Initialize your ARC

Section titled Initialize your ARC

1. Create and navigate to a local folder, which you want to initialize as an ARC, e.g. via file explorer or

   mkdir AthalianaColdStressSugar
   cd AthalianaColdStressSugar

2. Initialize your ARC by executing

   arc init

This created the general ARC folder structure:

• studies
• assays
• workflows
• runs
• isa.investigation.xlsx

Add investigation metadata

Section titled Add investigation metadata

1. Add an investigation identifier (-i or --investigationidentifier)

   arc investigation update -i AthalianaColdStressSugar

   Tip

   Avoid using spaces or special characters in the identifier.

2. Add a Title

   arc investigation --title "Arabidopsis thaliana cold acclimation"

3. Add a Description

   arc i --description "This experiment investigates the response of Arabidopsis thaliana to cold stress by subjecting plants to low-temperature conditions and monitoring physiological, molecular, and growth-related changes. Cold-treated plants are compared with control groups grown under optimal conditions to assess stress-related markers such as changes in protein abundance, sugar content, and growth rates. The goal is to identify key molecules and physiological responses involved in cold tolerance, contributing to the understanding of plant stress adaptation mechanisms."

4. Add Contacts

   arc i person register -f Jasmine -l Beetroot
   arc i person register -f Oliver -l Sage
   arc i person register -f Viola -l Canina --email viola@plantscience.xyz

Add studies and assays

Section titled Add studies and assays

1. Add a study with an identifier (-s, --assayidentifier)

   arc study add -s AthalianaColdStress

2. Add assays with an identifier (-a, --assay)

   arc assay add -s AthalianaColdStress -a SugarMeasurement
   arc assay add -s AthalianaColdStress -a Proteomics_MS
   arc assay add -s AthalianaColdStress -a Proteomics_DataAnalysis

   Note

   An assay must be linked to a study. If a study does not exist, it will be created automatically in this step.

The ARC Commander will add subdirectories to the studies and assays folders. Your ARC should look similar to this now:

• Directorystudies

  • DirectoryAthalianaColdStress

    • resources
    • protocols
    • isa.study.xlsx
  • …
• Directoryassays

  • DirectorySugarMeasurement

    • dataset
    • protocols
    • isa.assay.xlsx
  • …
• Directoryworkflows

  • …
• Directoryruns

  • …
• isa.investigation.xlsx

Sync with the DataHUB

Section titled Sync with the DataHUB

1. Synchronize your ARCs with the DataHUB using the command

   arc sync

2. If you did not connect your local ARC with a remote one so far, you can specify the remote address (-r or --remote) followed by the DataHUB URL, e.g.,

   arc sync -r https://git.nfdi4plants.org/<YourUserName>/<YourARC>

3. If no ARC exists under the given URL, you can force (-f or --force) the ARC Commander to create it.

   arc sync -f

   Note

   This will prompt an Error ERROR: GIT: fatal: repository 'https://git.nfdi4plants.org/<YourUserName>/<YourARC>' not found (Windows) or ERROR: GIT: fatal: couldn't find remote ref main (macOS). Don’t worry, the ARC is being created at that DataHUB during this step.

4. Check if the upload was successful by visiting your ARC at the respective URL in your browser.

Seeking help

Section titled Seeking help

The ARC Commander comes with a leveled help menu, that suggests suitable inputs on every level of command or subcommand. You can simply add -h or --help at the end of an ARC Commander action to display the respective help menu.

Some examples:

arc --help

arc investigation --h

arc investigation create --help

arc study --h

arc study add --help

arc assay remove --help

What’s next?

Section titled What’s next?

Here we only introduced the basic functions. After concluding this quickstart, you might want to explore the ARC Commander manual for a more detailed usage instruction.

In order to annotate the data in your ARC, explore the sections on studies and assays in the Getting Started guide. You can do this with ARCitect or Swate.

Tip

You were looking for even more code? Check out the ARCtrl docs for fully-fledged code control over ARCs.