All guides

Working from your own machine

Use the csroom command-line tool to pull, edit, test, and submit assignments in your own editor.

The csroom command-line tool lets you pull an assignment, edit it in your own editor, run its tests, and submit it without opening a browser. It works on the same files the browser shows, so you can switch between the two at any time. It works in classes where you are a student.

1. Get an API token

  1. Sign in to CS Room in a browser.
  2. Click API in the navigation bar.
  3. Name the token, pick when it expires, and click Create token.
  4. Copy the token. It is shown only once. If you lose it, revoke it and create a new one.

A token acts as your account. Don't share it or commit it to a repository.

2. Get the tool

The tool is a single Python file with no dependencies. It needs Python 3.10 or newer. Download it from api.csroom.org/api/cli/csroom.py, or from a terminal:

curl -fsSLO https://api.csroom.org/api/cli/csroom.py

Run it with python3 csroom.py .... To type csroom instead, make it executable and move it into a folder on your PATH:

chmod +x csroom.py
mv csroom.py ~/.local/bin/csroom

3. Sign in

csroom login

Paste your token when prompted, or pass it with --token. It is saved in ~/.config/csroom/config, readable only by you. If the CSROOM_TOKEN environment variable is set, the tool uses it instead of the saved token.

4. Work on an assignment

csroom classrooms                    # list your classes
csroom assignments "Period 3"        # list assignments in a class
csroom pull "Period 3" fizzbuzz      # download your copy into ./fizzbuzz
cd fizzbuzz
# ... edit with your own tools ...
csroom push "Period 3" fizzbuzz      # upload this directory as your working copy
csroom test "Period 3" fizzbuzz      # run the assignment's public tests
csroom submit "Period 3" fizzbuzz    # turn it in for grading

Name a class by its name or its id. If two of your classes share a name, use the id, which csroom classrooms lists.

What each command does

  • pull downloads your working copy into a folder named after the assignment, or into --dir. Before you change anything, that copy is the starter code. Pull refuses a folder that isn't empty unless you add --force, which overwrites files.
  • push replaces your working copy on CS Room with the current directory, or --dir. Anything on CS Room that isn't in that directory is deleted. Symlinks and .git, __pycache__, node_modules, .venv and .deps folders are never uploaded. A push is capped at 50 MB and 2,000 files. Pushing doesn't turn anything in; nothing is graded until you run csroom submit.
  • test runs the same public tests as the Run Tests button and prints the score.
  • submit turns in your working copy for grading. Once the assignment closes or your teacher locks your grade, submit returns an error. push still works, as editing in the browser does, but your grade no longer changes.

For teachers

Submissions, autograding, due-date collection and grade locks work the same as in the browser. The tool reaches only the signed-in student's own copy of each assignment.

Warn students that push replaces their whole working copy, so pushing the wrong folder deletes their work on CS Room. Ask them to revoke the token for any device they stop using.