Get the Nibras CLI running

You need Node.js ≥ 18, npm ≥ 9, and git before installing the CLI. Follow the steps for your OS.

# Recommended — nvm (no sudo, no permission issues)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.zshrc          # zsh default on macOS 10.15+ — use ~/.bashrc for bash
nvm install --lts
nvm use --lts
nvm alias default node
# Alternative — Homebrew
# brew install node

# Xcode Command Line Tools (built-in to macOS)
xcode-select --install
# Or via Homebrew:
# brew install git

node --version   # must be v18.x or higher
npm --version    # must be 9.x or higher
git --version

Install the current CLI release directly from GitHub. This pins the install to v1.0.2 and makes the nibras command available everywhere in your terminal.

npm install -g git+https://github.com/NibrasPlatform/nibras-cli.git#v1.0.2

Verify: nibras --version should start with v1.0.2, for example v1.0.2-499d7f9.

To reinstall later: nibras update --version v1.0.2. To remove the CLI: nibras uninstall.

Use nibras update --check to compare your installed version against the latest GitHub release before updating.

npm uninstall -g nibras @nibras/cli || true
rm -f "$(npm config get prefix)/bin/nibras"
rm -rf "$(npm root -g)/nibras" "$(npm root -g)/@nibras/cli"
npm install -g git+https://github.com/NibrasPlatform/nibras-cli.git#v1.0.2

Use an explicit --api-base-url for hosted onboarding so the CLI targets this deployment instead of the local dev default at http://127.0.0.1:4848. The login flow prints a one-time URL and short code, then tries to open the browser automatically unless you pass --no-open.

Credentials are saved in ~/Library/Application Support/nibras/config.json. Run nibras whoami after login to confirm the active session and linked GitHub account.

Before students can use the CLI, create a course and at least one project from the web dashboard.

1. Go to Instructor → New Course
2. Enter the course code (e.g. cs101), title, and term
3. Add a project with an allowed file path pattern
4. Copy the project key (e.g. cs101/assignment-1)

Run nibras setup with the project key to bootstrap the local directory. It writes .nibras/project.json and .nibras/task.md, initialises git if needed, and adds origin for the student repo.

nibras setup --project cs101/assignment-1

For bundle-backed projects, setup may download starter files and create the initial commit. If the target directory already has .git, setup refreshes the .nibras metadata instead of re-extracting starter files.

Specify a target directory: nibras setup --project cs101/a1 --dir ~/projects/a1

Use nibras test to run the manifest-configured test command for your OS. Pass --previous only when the project manifest supports it.

nibras test
nibras test --previous   # include previous milestone tests

A non-zero exit means the configured test command failed. Projects that do not opt in to previous-milestone runs will reject --previous.

nibras submit runs the configured local test command, stages only allowed files, creates a commit, pushes to origin, registers the submission, and polls for server-side verification.

nibras submit

A failing local test run does not abort submission. The CLI records the local result and server-side verification continues regardless.

Two diagnostic commands are available at any time:

nibras ping    # check API, auth, GitHub, GitHub App, and project status
nibras whoami  # show signed-in user and linked GitHub account

nibras ping is the fastest way to diagnose any problem — run it first. When run inside a project directory it also shows the project key and origin remote.

Students follow the same flow: install the CLI, run nibras login --api-base-url <api-url>, and nibras setup --project <key>. Share the project key with your class.

Students can view assignment instructions at any time with nibras task.

Start with nibras ping — it checks API reachability, auth, GitHub linkage, and App install status in one command. Use the OS tab above to filter fixes for your platform.