← Docs
⌨️

CLI Reference

@teachrepo/cli

Import repos, validate course YAML, and scaffold new courses from your terminal. Works standalone and in GitHub Actions CI/CD.

Installation

# Global install (recommended)
npm install -g @teachrepo/cli

# Or use without installing
npx @teachrepo/cli --help

Authentication

Set your TeachRepo API token as an environment variable, or pass it with --token. Get your token at Dashboard → Settings.

export TEACHREPO_TOKEN=tr_your_token_here

Commands

teachrepo import

Import a GitHub repository as a TeachRepo course.

Options

--repo <url>GitHub repository URL (required)
--token <token>TeachRepo API token (or set TEACHREPO_TOKEN)
--base-url <url>API base URL (default: https://teachrepo.com)
--dry-runValidate course.yml without importing

Examples

teachrepo import --repo=https://github.com/you/your-course
teachrepo import --repo=https://github.com/you/your-course --dry-run
TEACHREPO_TOKEN=tr_xxx teachrepo import --repo=https://github.com/you/your-course
teachrepo validate

Validate a course.yml file without importing.

Options

--file <path>Path to course.yml (default: ./course.yml)
--verboseShow detailed validation output including summary

Examples

teachrepo validate
teachrepo validate --verbose
teachrepo validate --file=./my-course.yml
teachrepo new <course-name>

Scaffold a new course from the official template.

Options

--template <t>Template: basic | quiz | sandbox (default: basic)
--slug <slug>URL slug (default: kebab-case of course-name)

Examples

teachrepo new "Advanced Git for Engineers"
teachrepo new "Python Async" --template=sandbox
teachrepo new "React Patterns" --slug=react-patterns --template=quiz
teachrepo whoami

Show the authenticated TeachRepo user.

Options

--token <token>TeachRepo API token (or set TEACHREPO_TOKEN)

Examples

teachrepo whoami

GitHub Actions

Add the CLI to your workflow to auto-import on every push to main. The course template includes this workflow pre-configured.

name: Deploy to TeachRepo
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @teachrepo/cli
      - run: teachrepo import --repo="${{ github.repositoryUrl }}"
        env:
          TEACHREPO_TOKEN: ${{ secrets.TEACHREPO_TOKEN }}

Source Code

The CLI is open-source under MIT. Issues and PRs welcome.

⭐ github.com/ErlisK/teachrepo-cli →
← All docsCourse Template →