nsg-cli 0.1.0

CLI tool for the Neuroscience Gateway (NSG) BRAIN Initiative API
Documentation
nsg-cli-0.1.0 has been yanked.

NSG CLI

A command-line interface for the Neuroscience Gateway (NSG) BRAIN Initiative API.

Features

  • Secure credential storage - Store NSG credentials in ~/.nsg/credentials.json
  • Job management - Submit, monitor, and download results from NSG HPC jobs
  • Beautiful CLI - Colored output with progress indicators
  • XML API support - Full support for NSG's REST API (XML-based)
  • Multiple commands - Login, list, status, submit, and download operations

Installation

From crates.io

cargo install nsg-cli

Build from source

cd nsg-cli
cargo build --release

The binary will be at target/release/nsg.

Install globally

cargo install --path .

This installs the nsg binary to ~/.cargo/bin/.

Quick Start

1. Login

First, authenticate with your NSG credentials:

nsg login

You'll be prompted for:

  • NSG Username
  • NSG Password (hidden input)
  • NSG Application Key

Your credentials are stored in ~/.nsg/credentials.json with secure permissions (0600 on Unix).

Get NSG credentials at: https://www.nsgportal.org/

2. List Jobs

View all your NSG jobs:

nsg list

For detailed status of each job (slower):

nsg list --detailed

3. Check Job Status

Monitor a specific job:

nsg status <JOB_ID>

Examples:

nsg status NGBW-JOB-PY_EXPANSE-xxxxx
nsg status https://nsgr.sdsc.edu:8443/cipresrest/v1/job/username/NGBW-JOB-PY_EXPANSE-xxxxx

4. Submit a Job

Submit a new job to NSG:

nsg submit <ZIP_FILE> --tool <TOOL_NAME>

Example:

nsg submit my_analysis.zip --tool PY_EXPANSE

Available tools:

  • PY_EXPANSE - Python on EXPANSE (default)
  • GPU_PY_EXPANSE - GPU-accelerated Python
  • Other NSG tools as supported

5. Download Results

Download results from a completed job:

nsg download <JOB_ID>

Specify output directory:

nsg download <JOB_ID> --output ./my_results

Commands

nsg login

Authenticate and save credentials.

Options:

  • -u, --username <USERNAME> - NSG username (or prompt)
  • -p, --password <PASSWORD> - NSG password (or prompt securely)
  • -a, --app-key <APP_KEY> - NSG application key (or prompt)
  • --no-verify - Skip connection test

Example:

nsg login --username myuser --app-key MY_APP_KEY

nsg list

List all jobs for the authenticated user.

Options:

  • --detailed - Fetch detailed status for each job (slower)

Example:

nsg list --detailed

nsg status <JOB>

Check status of a specific job.

Arguments:

  • <JOB> - Job URL or Job ID

Example:

nsg status NGBW-JOB-PY_EXPANSE-xxxxx

nsg submit <ZIP_FILE>

Submit a new job to NSG.

Arguments:

  • <ZIP_FILE> - Path to ZIP file containing job data

Options:

  • -t, --tool <TOOL> - NSG tool to use (default: PY_EXPANSE)
  • --no-wait - Don't wait for job submission confirmation

Example:

nsg submit job_data.zip --tool PY_EXPANSE

nsg download <JOB>

Download results from a completed job.

Arguments:

  • <JOB> - Job URL or Job ID

Options:

  • -o, --output <DIR> - Output directory (default: ./nsg_results)

Example:

nsg download NGBW-JOB-PY_EXPANSE-xxxxx --output ./results

NSG Job Package Structure

When submitting jobs, NSG expects a specific ZIP structure. For Python jobs:

job.zip
└── modeldir/
    ├── input.py          # Main Python script (required)
    ├── data.edf          # Input data files
    ├── params.json       # Configuration
    └── ...               # Other files

The main script should be named input.py for PY_EXPANSE tool.

Configuration

Credentials are stored in: ~/.nsg/credentials.json

Format:

{
  "username": "your_username",
  "password": "your_password",
  "app_key": "your_app_key"
}

Security:

  • On Unix systems, the file permissions are set to 0600 (read/write for owner only)
  • Never commit this file to version control
  • Keep your credentials secure

API Documentation

This CLI interfaces with the NSG REST API:

  • Base URL: https://nsgr.sdsc.edu:8443/cipresrest/v1
  • Authentication: HTTP Basic Auth + cipres-appkey header
  • Response format: XML

Development

Project Structure

nsg-cli/
├── Cargo.toml
├── src/
│   ├── main.rs           # CLI entry point
│   ├── lib.rs            # Library exports
│   ├── client.rs         # NSG API client
│   ├── config.rs         # Credential management
│   ├── models.rs         # Data structures & XML parsing
│   └── commands/         # CLI commands
│       ├── mod.rs
│       ├── login.rs
│       ├── list.rs
│       ├── status.rs
│       ├── submit.rs
│       └── download.rs
└── README.md

Dependencies

  • clap - CLI argument parsing
  • reqwest - HTTP client
  • quick-xml - XML parsing
  • serde - Serialization
  • colored - Terminal colors
  • indicatif - Progress bars
  • rpassword - Secure password input

Building

cargo build          # Debug build
cargo build --release  # Release build (optimized)
cargo test           # Run tests
cargo check          # Type checking only (fast)

Troubleshooting

Authentication Failed

If login fails:

  1. Verify credentials at https://www.nsgportal.org/
  2. Check that your NSG account is active
  3. Ensure application key is correct
  4. Try using --no-verify to skip connection test and save credentials anyway

Job Not Found

If status or download can't find a job:

  1. Verify job ID is correct
  2. Use nsg list to see all your jobs
  3. Try using the full job URL instead of just the ID

Download Failed

If results download fails:

  1. Check job is in COMPLETED stage with nsg status
  2. Verify job has results available
  3. Check output directory permissions

License

MIT License

Related Projects

  • DDALAB - Delay Differential Analysis Laboratory
  • NSG Portal - Neuroscience Gateway web interface

Contributing

This tool was created as part of the DDALAB project. For issues or contributions, please use the DDALAB repository.

Contact

For NSG-related issues: nsghelp@sdsc.edu For DDALAB issues: https://github.com/sdraeger/DDALAB/issues