Command Line Interface (Beta)

The Pawtograder CLI is a command-line tool for instructors and site administrators to automate course management tasks. It provides programmatic access to Pawtograder’s core functionality, enabling bulk operations, scripting, and integration with other tools.

The CLI is currently in beta. Commands and options may change in future releases.

Installation

The CLI is included in the Pawtograder platform repository. To use it:

# Clone the repository
git clone https://github.com/pawtograder/platform.git
cd platform

# Install dependencies
npm install

# Run the CLI
npm run cli -- <command> [options]

Authentication

Before using the CLI, you must authenticate with an API token.

Creating an API Token

Log in to Pawtograder
Navigate to your account settings
Go to the “API Tokens” section
Click “Create New Token”
Give your token a descriptive name and select appropriate scopes
Copy the generated token (you won’t be able to see it again)

Logging In

# Interactive login (prompts for token)
npm run cli -- login

# Login with token directly
npm run cli -- login --token YOUR_TOKEN_HERE

# Login to a custom instance
npm run cli -- login --token YOUR_TOKEN_HERE --url https://your-instance.com/functions/v1/cli

Managing Authentication

# Check current user
npm run cli -- whoami

# Log out
npm run cli -- logout

Available Commands

Classes

Manage course classes.

# List all classes you have access to
npm run cli -- classes list

Assignments

Manage assignments across classes:

# List assignments for a class
npm run cli -- assignments list --class <identifier>

# Show assignment details
npm run cli -- assignments show <identifier> --class <identifier>

# Copy assignments between classes
npm run cli -- assignments copy \
  --source-class <slug> \
  --target-class <slug> \
  --all

# Copy with schedule (CSV file with dates)
npm run cli -- assignments copy \
  --source-class <slug> \
  --target-class <slug> \
  --schedule <file.csv>

# Delete an assignment
npm run cli -- assignments delete <identifier> \
  --class <identifier> \
  --force

Assignment copy options

--assignment <slug>: Copy a single assignment
--all: Copy all assignments from source class
--schedule <file>: Copy assignments with date overrides from CSV
--dry-run: Preview changes without making them
--skip-repos: Skip repository operations
--skip-rubrics: Skip rubric copying
--skip-surveys: Skip survey copying
--workdir <path>: Local directory for git clones (required for repo operations)
--concurrency <n>: Parallel operations (1-8, default 4)
--delay-ms <ms>: Delay between clone batches in milliseconds

Rubrics

Import and export rubrics in YAML format:

# List rubrics for an assignment
npm run cli -- rubrics list \
  --assignment <identifier> \
  --class <identifier>

# Export rubric to YAML
npm run cli -- rubrics export \
  --assignment <identifier> \
  --class <identifier> \
  --type grading \
  --output rubric.yml

# Import rubric from YAML
npm run cli -- rubrics import \
  --assignment <identifier> \
  --class <identifier> \
  --file rubric.yml \
  --type grading

Rubric types: grading, self_review, meta

Surveys

Copy surveys between classes:

# Copy all surveys
npm run cli -- surveys copy \
  --source-class <slug> \
  --target-class <slug> \
  --all

# Copy single survey
npm run cli -- surveys copy \
  --source-class <slug> \
  --target-class <slug> \
  --survey <uuid|title>

# Link to target assignment
npm run cli -- surveys copy \
  --source-class <slug> \
  --target-class <slug> \
  --all \
  --target-assignment <slug>

Flashcards

Copy flashcard decks between classes:

# Copy all decks
npm run cli -- flashcards copy \
  --source-class <slug> \
  --target-class <slug> \
  --all

# Copy single deck
npm run cli -- flashcards copy \
  --source-class <slug> \
  --target-class <slug> \
  --deck <name>

Submissions

Import comments and artifacts:

# Import submission comments
npm run cli -- submissions comments import \
  --class <identifier> \
  --assignment <identifier> \
  --file batch-results.json \
  --author-profile-id <uuid>

# Sync comments (insert + soft-delete missing)
npm run cli -- submissions comments sync \
  --class <identifier> \
  --assignment <identifier> \
  --file batch-results.json \
  --rubric-part-id <id>

# Import artifacts
npm run cli -- submissions artifacts import \
  --class <identifier> \
  --assignment <identifier> \
  --file manifest.json \
  --overwrite

Repository maintenance

The CLI provides local git/rsync workflows for student repository operations. These commands fetch metadata from the API and perform git operations via SSH on your machine.

List repositories

npm run cli -- repos list \
  --class <identifier> \
  --assignment <identifier>

Sync grade workflow

Sync .github/workflows/grade.yml from handout to all student repos:

npm run cli -- repos sync-grade-workflow \
  --class <identifier> \
  --assignment <identifier> \
  --workdir <path>

Options:

--dry-run: Preview changes only
--concurrency <n>: Parallel operations (1-8, default 2)
--delay-ms <ms>: Delay between batches

Cross-assignment copy

Copy files from source assignment repos to target assignment repos after source due date:

npm run cli -- repos copy-after-source-due \
  --class <identifier> \
  --source-assignment <identifier> \
  --target-assignment <identifier> \
  --workdir <path>

Options:

--dry-run: Preview with rsync -n only
--mirror-delete: Pass rsync —delete (excludes .git)
--concurrency <n>: Parallel operations (1-8, default 2)

Environment variables

PAWTOGRADER_HTTP_TIMEOUT_MS: HTTP timeout in milliseconds (default: system default)
DEBUG=1: Enable verbose HTTP logging
PAWTOGRADER_VERBOSE=1: Alternative verbose flag

Common workflows

Copy course to new semester

# 1. Copy all assignments with repositories
npm run cli -- assignments copy \
  --source-class cs3500-fall-2025 \
  --target-class cs3500-spring-2026 \
  --all \
  --workdir ~/pawtograder-repos

# 2. Copy surveys
npm run cli -- surveys copy \
  --source-class cs3500-fall-2025 \
  --target-class cs3500-spring-2026 \
  --all

# 3. Copy flashcard decks
npm run cli -- flashcards copy \
  --source-class cs3500-fall-2025 \
  --target-class cs3500-spring-2026 \
  --all

Bulk update grade workflows

# Sync grade.yml to all student repos
npm run cli -- repos sync-grade-workflow \
  --class cs3500-spring-2026 \
  --assignment hw1 \
  --workdir ~/pawtograder-repos \
  --concurrency 4

Export and modify rubrics

# Export rubric
npm run cli -- rubrics export \
  --assignment hw1 \
  --class cs3500 \
  --type grading \
  --output hw1-rubric.yml

# Edit hw1-rubric.yml locally

# Import modified rubric
npm run cli -- rubrics import \
  --assignment hw1 \
  --class cs3500 \
  --file hw1-rubric.yml \
  --type grading

Error handling

The CLI provides detailed error messages and exit codes:

0: Success
1: General error
2: Authentication error
3: Not found error
4: Validation error

Use --help with any command to see detailed usage information:

npm run cli -- assignments --help
npm run cli -- assignments copy --help

Best practices

Use dry-run mode: Always test with --dry-run before running destructive operations
Backup data: Export important data before making bulk changes
Use workdir: Specify a dedicated working directory for git operations to avoid conflicts
Monitor progress: The CLI provides detailed logging for long-running operations
Secure tokens: Store API tokens securely and never commit them to version control
Use specific identifiers: Prefer slugs or IDs over names for reliability

Troubleshooting

Authentication issues

If you encounter authentication errors:

Verify your token is valid: npm run cli -- whoami
Check token scopes match the required permissions
Ensure you’re connecting to the correct instance

Repository operations

If git operations fail:

Ensure you have SSH access to GitHub
Verify the workdir has sufficient disk space
Check network connectivity
Try reducing --concurrency for rate-limited operations

Performance

For large operations:

Use --concurrency to control parallel operations
Add --delay-ms to avoid rate limiting
Consider running operations during off-peak hours

Getting Started

Assignments

Instructor Dashboard

Discussion & Engagement

Office Hours

Gradebook

AI Assistance

Automation

Reference

CLI

Command Line Interface (Beta)

Installation

Authentication

Creating an API Token

Logging In

Managing Authentication

Available Commands

Classes

Assignments

Assignment copy options

Rubrics

Surveys

Flashcards

Submissions

Repository maintenance

List repositories

Sync grade workflow

Cross-assignment copy

Environment variables

Common workflows

Copy course to new semester

Bulk update grade workflows

Export and modify rubrics

Error handling

Best practices

Troubleshooting

Authentication issues

Repository operations

Performance

​Command Line Interface (Beta)

​Installation

​Authentication

​Creating an API Token

​Logging In

​Managing Authentication

​Available Commands

​Classes

​Assignments

​Assignment copy options

​Rubrics

​Surveys

​Flashcards

​Submissions

​Repository maintenance

​List repositories

​Sync grade workflow

​Cross-assignment copy

​Environment variables

​Common workflows

​Copy course to new semester

​Bulk update grade workflows

​Export and modify rubrics

​Error handling

​Best practices

​Troubleshooting

​Authentication issues

​Repository operations

​Performance

Command Line Interface (Beta)

Installation

Authentication

Creating an API Token

Logging In

Managing Authentication

Available Commands

Classes

Assignments

Assignment copy options

Rubrics

Surveys

Flashcards

Submissions

Repository maintenance

List repositories

Sync grade workflow

Cross-assignment copy

Environment variables

Common workflows

Copy course to new semester

Bulk update grade workflows

Export and modify rubrics

Error handling

Best practices

Troubleshooting

Authentication issues

Repository operations

Performance