Skip to content

Setup and Installation

Jump to bottom
Harrison Surma edited this page Apr 30, 2025 · 2 revisions

Setup and Installation Guide

This guide will help you install and configure Canvas-CLI, a command-line tool designed for interacting with Canvas Learning Management System.

Prerequisites

Before installing Canvas-CLI, ensure you have the following:

  • Python 3.9 or higher installed
  • pip (Python package installer)
  • A Canvas LMS account with API access

Installation Methods

Method 1: Install from PyPI (Recommended)

The easiest way to install Canvas-CLI is from PyPI:

pip install canvas-cmd

This will install the latest stable version along with all dependencies.

Note

I am so aware how unhelpful it is that it is canvas-cmd on PyPI and canvas-cli on GitHub. I prefer canvas-cli as a name, but it was already taken on PyPI. I will make a decision on this in the future, but for now, it is canvas-cmd on PyPI and canvas-cli everywhere else.

Method 2: Install from Source

For the latest development version or to contribute to the project:

  1. Clone the repository:

    git clone https://github.com/PhantomOffKanagawa/canvas-cli.git
cd canvas-cli

  2. Install in development mode:

    pip install -e .

Initial Configuration

After installation, you need to configure Canvas-CLI with your Canvas API token:

canvas config set --global token YOUR_CANVAS_API_TOKEN
canvas config set --global host your-institution.instructure.com

Obtaining Your Canvas API Token

  1. Log in to your Canvas account
  2. Navigate to Account > Settings
  3. Scroll down to "Approved Integrations"
  4. Click "New Access Token"
  5. Enter a purpose (e.g., "Canvas-CLI") and an optional expiration date
  6. Click "Generate Token"
  7. Copy the token shown (you will only see it once)

Verifying Installation

To verify that CanvasLMS-CLI is correctly installed and configured:

canvas --help

This should display the help message with available commands.

canvas config --global list

This should display your configured settings.

Project Configuration

For a better workflow, you can initialize a project directory with Canvas course and assignment information:

# Create a project directory
mkdir my_assignment
cd my_assignment

# Initialize with Canvas information
canvas init

Follow the interactive prompts to select your course and assignment.

Tip

Many commands have the --tui option, which provides a text-based user interface for selecting courses and assignments. This is useful as it saves you from getting IDs from the web interface.

Troubleshooting

Common Issues

  1. "Command not found" error

    Ensure the Python scripts directory is in your PATH. You may need to restart your terminal after installation.

  2. Authentication errors

    Check that your API token is valid and correctly entered. Tokens have specific permissions and may expire.

  3. error: externally-managed-environment

    Check you are in a virtual environment if you want to use one, else I recommend using "pipx" for a global installation.

Getting Help

If you encounter any issues not covered here:

Next Steps

After installation and configuration, check out the Usage Guide for detailed instructions on how to use CanvasLMS-CLI for your Canvas assignments.

Clone this wiki locally