4    Diderot Command Line Interface

Diderot offers a command line interface to simplify interaction with the platform via the command line. The main advantage of the CLI over the web interface is that it is possible to upload materials onto the platform more quickly.

important
Important (Sources and Contributions)

To download the CLI, please clone this github repository and follow the instructions in README.md.

The Diderot CLI is public. Feel free to contribute or open an issue if there are any commands or utilities that you think would be useful to have. Please send feedback by opening an issue.

This guide is public and it source are available in this repo. Please send feeback by opening an issue.

1  Basic Usage

Use the diderot_student or diderot_admin scripts to interface with the CLI. For help about the CLI, use the -h or --help commands.

1.1  Credential Management

Credentials are passed to the CLI in one of two ways. The first is to simply pass your credentials via the CLI using the --username and --password flags on the CLI. A more convenient (and recommended) way is to use a credentials file. The credential file format is simply a text file with your username on the first line and your password on the second. Use the --credentials argument to point the CLI towards a file containing your credentials. For easier usage, the CLI automatically looks at the files ~/private/.diderot/credentials and ~/.diderot/credentials for a credentials file of this form. If this file exists, then the CLI will automatically log you in, and no credentials need to be explicitly provided to the CLI.

important
Important

Your credentials file must have only "owner can read and write" permissions. You can run chmod 600 <credentials file> to set the appropriate permissions.

Example

An example credential file is below.

MyUsername  
MyPassword  
important
Important

If you are using a custom path (rather than the default path) for your credentials file, or passing your username and password explicitly, then you will need supply these arguments as the first in the command. Specifically, the --username/--password or --credentials arguments must be passed to the CLI as the first argument, before additional commands!

For example, this command is correct:

$ diderot_student --credentials Path/To/My/Creds list_courses  

This command is incorrect:

$ diderot_student list_courses --credentials Path/To/My/Creds  
2  Student Interface
  • list_courses: List all available course labels that the user can access. Operations which require a course input must use the one of the labels returned from this command.

  • list_assignments: Lists all assignments for a course.

  • download_assignment: Downloads all handout/writeup files (if present) from a target course and assignment into the current directory.

  • submit_assignment: Submit a file to a given course and homework.

More details about each command are below.

2.1  list_courses

list_courses lists all course labels that the user has access to. The labels returned from list_courses must be used as arguments to all other operations that require a course label. It accepts 0 arguments.

Example Usage:

$ diderot_student list_courses  
2.2  list_assignments

list_assignments is used to list all available assignments for a particular course. It accepts only 1 argument.

  • course: Course label to list homeworks of.

Example Usage:

$  diderot_student list_assignments courselabel  
2.3  download_assignment

download_assignment is used to download handout files associated with an assignment. It attempts to download all handout files into the current directory. It accepts 2 arguments.

  • course: Course label that the homework belongs to.

  • homework: Name of the homework to download handouts of.

Example Usage:

$  diderot_student download_assignment courselabel homeworkname  
2.4  submit_assignment

submit_assignment is used to submit handin files to an assignment. Please make sure to check your homework handouts to see what file types your homework expects. It accepts 3 arguments.

  • course: Course label that the homework belongs to.

  • homework: Name of the homework to submit to.

  • handin_path: Path to the handin file.

Example Usage:

$  diderot_student submit_assignment courselabel homeworkname ~/Path/To/My/Handin  
3  Admin Interface

The admin CLI contains all the above commands, and expands the set to include some commands relating to manipulation of books and assignments.

  • list_books: List all books, can optionally filter by course.

  • list_parts: List all parts of a book.

  • list_chapters: List all chapters of a book.

  • create_part: List all parts of a book.

  • create_chapter: Create a chapter in a given part of a book. Optionally specify the new chapter’s label and or title. If not, these values are filled in with a default.

  • {release/unrelease}_chapter: Release or unrelease an existing chapter.

  • upload_chapter: Update the content of an existing chapter. Upload either a standalone pdf, pdf of a slideshow, or an xml document and image attachments. The image upload accepts filenames, globs, and folder names (folders are recursively traversed).

  • update_assignment: Update the files relating to an existing homework on Diderot. Upload any of the autograder tar, autograder makefile, pdf writeup, and student handout.

3.1  list_books

list_books is used to list book labels that the user has access to. The result from list_books is used as the argument book label for commands that require a book label. It accepts 2 arguments.

  • course: Course label that the target book belongs to.

  • --all: Optional flag to list all books regardless of course. Not to be used when specifying a course.

Example Usage:

$  diderot_admin list_books courselabel  
$  diderot_admin list_books --all  
3.2  list_parts

list_parts is used list the parts and numbers within a target book. It accepts 2 arguments.

  • course: Course label that the target book belongs to.

  • book: Label of the target book.

Example Usage:

$  diderot_admin list_parts courselabel booklabel  
3.3  list_chapters

list_chapters is used list the chapters and numbers within a target book. It accepts 2 arguments.

  • course: Course label that the target book belongs to.

  • book: Label of the target book.

Example Usage:

$  diderot_admin list_chapters courselabel booklabel  
3.4  create_part

create_part is used to create a part within a target book. It accepts 5 arguments.

  • course: Course label that the target book belongs to.

  • book: Label of the target book.

  • title: Title to give to the newly created part.

  • number: Number to give the newly created part.

  • --label: Optional label to give to the newly created part. It defaults to a random value if not provided.

The command will error out if there already exists a part within the book with the same number.

Example Usage:

$ diderot_admin create_part courselabel booklabel title number --label new-label  
3.5  create_chapter

create_chapter is used to create a chapter within a target book. It accepts 6 arguments.

  • course: Course label that the target book belongs to.

  • book: Label of the target book.

  • --part: Number of the part to create the chapter within. This argument is not used when the target book is a booklet.

  • --number: Number to give the newly created chapter.

  • --title: Optional title to give to the newly created chapter. It defaults to ’Chapter’.

  • --label: Optional label to give to the newly created chapter. It defaults to a random value if not provided.

The command will error out if there already exists a chapter within the book with the same number.

Example Usage:

$ diderot_admin create_chapter courselabel booklabel --part partnum \  
  --number newnum --title newtitle --label newlabel  
3.6  release/unrelease_chapter

release_chapter and unrelease_chapter are used to release or unrelease a chapter. They each accept 3 arguments.

  • course: Course label to release a chapter in.

  • book: Book label to release a chapter in.

  • --chapter_number or --chapter_label: Use one of these arguments to specify which chapter to release. Use either the chapter’s number within the book, or its label.

Example Usage:

$ diderot_admin release_chapter courselabel booklabel --chapter_label chapterlabel  
$ diderot_admin unrelease_chapter courselabel booklabel --chapter_label chapterlabel  
3.7  upload_chapter

upload_chapter is used to upload PDF, slide, or xml/mlx content to a chapter. It accepts quite a few arguments and combinations.

  • course: Course label to upload chapter to.

  • book: Book label to upload a chapter to.

  • --chapter_number or --chapter_label: Use one of these arguments to specify which chapter to upload content to. Use either the chapter’s number within the book, or its label.

  • --pdf or --slides or --xml: Use one of these arguments, specifying the desired file type to upload. Note that your slides must be in a PDF format to use the --slides argument. The --xml argument accepts both XML and MLX file formats.

  • --video_url: Optional URL to a video to embed within the chapter. This argument can only be used with the --pdf and --slides arguments.

  • --xml_pdf: Optional path to a PDF version of the XML content for printing. This argument can only be used with the --xml argument.

  • --attach: Optional list of paths to attachments to upload along with an XML chapter upload. This argument can only be used with the --xml argument. The command accepts paths to individual files, globs, and folders. Folders are recursively traversed.

Example Usage:

$ diderot_admin upload_chapter courselabel bookname --chapter_number chapternumber \  
  --pdf Path/to/Pdf --video_url someurl  
  
$ diderot_admin upload_chapter courselabel bookname --chapter_number chapternumber \  
  --slides Path/to/slides --video_url someurl  
  
$ diderot_admin upload_chapter courselabel bookname --chapter_number chapternumber \  
  --xml Path/to/Xml --xml_pdf Path/To/XmlPdf \  
  --attach Path/To/File Path/To/Folder/ Path/With/Glob/*  
3.8  update_assignment

update_assignment is used to update files related to an assignment on Diderot. It accepts 6 arguments.

  • course: Course label that the assignment belongs to.

  • homework: Name of the assignment to update.

  • --autograde-tar: Optional path to the autograder tar file for the assignment. The autograde.tar file contains what is needed to run the assignment’s autograder.

  • --autograde-makefile: Optional path to the autograde-Makefile for the assignment. The autograde-Makefile is used to execute the autograder on a student handin.

  • --writeup: Optional path to a PDF writeup of the assignment.

  • --handout: Optional path to a handout file that students can download to start the assignment.

Example Usage:

$ didetot_admin update_assignment courselabel homeworkname \  
  --autograde-tar Path/To/Tar \  
  --autograde-makefile Path/To/Makefile \  
  --writeup Path/To/Writeup --handout Path/To/Handout