Get started using the Spell CLI tool, or skip down to What's Next for ideas for your first project.

Create a Spell Account

If you already have an account continue on to the next step. If you don’t have an account yet you can sign up on our registration page.

Install Dependencies

Spell requires Python, pip, and Git (and optionally rsync) in order to install and run.

To install pip, you can find installation instructions in pip's docs.


For Windows users, we recommend installing Anaconda as it comes with pip and python.

  1. Install Anaconda Python 3.7 (or Miniconda 3) from https://anaconda.com/distribution

  2. Install Git, from https://git-scm.com/download/win, accepting all defaults in the wizard (which includes adding Git to the PATH)

Install the CLI Tool

The Spell command can be installed or upgraded with pip.

$ pip install spell


For Windows users, open Anaconda Prompt (not Windows cmd) and run pip install spell

Once you have the Spell CLI installed, try running it by typing spell into terminal. You should see a helpful list of subcommands. You can add --help as an option to any command to see a list of options, potential values, and an explanation of their use. All the CLI documentation is also available online in our CLI reference docs.

Log Into Spell

The first time Spell is used on a machine, you will need to log in using your Spell account credentials:

$ spell login

This will prompt you for your username or email and your password. The credentials you use here are the same ones you use to login to the web console. If you need to reset your password, you can do so on your account settings page.

If your login is successful you will see the following greeting,

Hello <username>!

Otherwise, you will receive an error message. If you are sure you are using the correct password and username and are not able to login to your account, please contact us at support@spell.run.

You can check your current login status at any time using:

$ spell whoami

Run Your First Run

Spell commands are typically run within a Git repository, but do not need to be. If you are not within a Git repository, Spell will ask you to confirm that you want to proceed since no files from your local computer will be transferred to Spell for the run. Type y to continue with the run.

For ideas on projects and step-by-step walkthroughs, check out our Guides.

For in-depth information on runs, read more in the What is a Run section of our docs.

If a run is initiated within a Git repository, Spell will automatically sync committed changes and use them within the run. Uncommitted changes will also be included as a separate patch, which can be downloaded later via the web console. Changes to untracked files will cause a warning, but you will still be allowed to proceed with your run.

Commands are run with spell run "cmd-to-run". A good first command is:

$ spell run "echo hello world"

A sample response to this run is:

✨ Casting spell #1…
✨ Stop viewing logs with ^C
✨ Run is running
hello world

What's Next?

For more ideas on projects, and to see the Spell CLI in action, check out our Guides.