Installation Guide¶

This guide covers all the ways to install Canvas CLI on your system.

System Requirements¶

Operating Systems: macOS, Linux, Windows
Architecture: amd64, arm64
Go Version (if building from source): 1.21 or later

Installation Methods¶

Method 1: Homebrew (macOS/Linux) - Recommended¶

# Add the Canvas CLI tap
brew tap jjuanrivvera/canvas-cli

# Install Canvas CLI
brew install canvas-cli

# Verify installation
canvas version

Upgrading¶

brew upgrade canvas-cli

Method 2: Using Go¶

If you have Go installed:

# Install latest version
go install github.com/jjuanrivvera/canvas-cli/cmd/canvas@latest

# Install specific version
go install github.com/jjuanrivvera/canvas-cli/cmd/canvas@v1.0.0

# Verify installation
canvas version

Method 3: Download Binary (All Platforms)¶

Visit the Releases page
Download the appropriate binary for your platform:
macOS (Intel): canvas_v1.0.0_Darwin_x86_64.tar.gz
macOS (Apple Silicon): canvas_v1.0.0_Darwin_arm64.tar.gz
Linux (64-bit): canvas_v1.0.0_Linux_x86_64.tar.gz
Windows (64-bit): canvas_v1.0.0_Windows_x86_64.zip

Extract the archive:

# macOS/Linux
tar -xzf canvas_*.tar.gz

# Windows - use your preferred extraction tool

Move the binary to your PATH:

# macOS/Linux
sudo mv canvas /usr/local/bin/

# Windows - add to PATH or move to C:\Windows\System32\

Verify installation:
```
canvas version
```

Method 4: Docker¶

# Run Canvas CLI in Docker
docker run ghcr.io/jjuanrivvera/canvas-cli:latest version

# Create an alias for easier use
alias canvas='docker run -it --rm -v ~/.canvas-cli:/root/.canvas-cli ghcr.io/jjuanrivvera/canvas-cli:latest'

# Now use as normal
canvas courses list

Method 5: Build from Source¶

# Clone the repository
git clone https://github.com/jjuanrivvera/canvas-cli.git
cd canvas-cli

# Build
make build

# Install
make install

# Verify
canvas version

Shell Completion¶

Enable tab completion for your shell:

Bash¶

# Generate completion script
canvas completion bash > /etc/bash_completion.d/canvas

# Or for user-level installation
canvas completion bash > ~/.canvas-completion.bash
echo 'source ~/.canvas-completion.bash' >> ~/.bashrc

Zsh¶

# Generate completion script
canvas completion zsh > "${fpath[1]}/_canvas"

# Reload completions
autoload -U compinit && compinit

Fish¶

# Generate completion script
canvas completion fish > ~/.config/fish/completions/canvas.fish

PowerShell¶

# Generate completion script
canvas completion powershell | Out-String | Invoke-Expression

# Add to profile for persistence
canvas completion powershell >> $PROFILE

Verify Installation¶

After installation, verify everything is working:

# Check version
canvas version

# Run diagnostics
canvas doctor

# Test authentication (will prompt for credentials)
canvas auth login --instance https://canvas.instructure.com

Troubleshooting¶

Command not found¶

If you get command not found, ensure the installation directory is in your PATH:

# Check PATH
echo $PATH

# Add to PATH (macOS/Linux)
export PATH="$PATH:/usr/local/bin"

# Make permanent by adding to ~/.bashrc or ~/.zshrc
echo 'export PATH="$PATH:/usr/local/bin"' >> ~/.bashrc

Permission denied¶

If you get permission errors:

# Make binary executable
chmod +x /path/to/canvas

# Or use sudo for installation
sudo mv canvas /usr/local/bin/

macOS Security Warning¶

On macOS, you may need to allow the app in System Preferences:

Try to run canvas version
Go to System Preferences > Security & Privacy
Click "Allow Anyway" for Canvas CLI
Run the command again

Updating¶

Homebrew¶

brew upgrade canvas-cli

Go¶

go install github.com/jjuanrivvera/canvas-cli/cmd/canvas@latest

Binary¶

Download and replace the binary with the latest version from the releases page.

Docker¶

docker pull ghcr.io/jjuanrivvera/canvas-cli:latest

Uninstalling¶

Homebrew¶

brew uninstall canvas-cli
brew untap jjuanrivvera/canvas-cli

Go¶

rm $(which canvas)

Binary¶

# Find and remove the binary
sudo rm /usr/local/bin/canvas

# Remove configuration and cache
rm -rf ~/.canvas-cli

Docker¶

docker rmi ghcr.io/jjuanrivvera/canvas-cli:latest

Next Steps¶

After installation, continue with: - Authentication Guide - Set up OAuth - Command Reference - Learn available commands - Tutorials - See common use cases