CLI overview

The Motia CLI provides commands for creating new projects, building applications, and managing development workflows. It supports both JavaScript/TypeScript and Python projects.

Installation

Using Homebrew (macOS/Linux)

brew tap MotiaDev/tap
brew install motia-cli

Using shell script

curl -fsSL https://raw.githubusercontent.com/MotiaDev/motia-cli/main/install.sh | sh

Verify installation

motia-cli --version

Prerequisites

Node.js 18+ - For TypeScript/JavaScript projects
Python 3 - For Python projects (optional)
iii engine - The Rust-based runtime that powers Motia (auto-installed during project creation)

Available commands

The Motia CLI provides commands for both the standalone CLI tool and the framework-level commands:

Standalone CLI (motia-cli)

Command	Description
`motia-cli create`	Create a new Motia project with iii configuration

Framework commands (motia/motia-iii)

These commands are available within a Motia project:

Command	Description
`motia dev`	Build and run the project in development mode
`motia build`	Build the project for production deployment
`motia typegen`	Generate TypeScript types from steps and streams

Python-specific commands

When working with Python projects, use the motia command:

Command	Description
`motia run`	Discover and run steps and streams
`motia dev`	Run in development mode with optional file watching
`motia build`	Generate production build at dist/index.py
`motia typegen`	Generate schema manifest from steps and streams

Quick start

Create your first Motia application:

# Create a new project
motia-cli create my-app

# Navigate to project directory
cd my-app

# Start the iii engine
iii -c iii-config.yaml

The CLI will:

Auto-detect and install the iii engine if needed
Prompt you to select a language (TypeScript, JavaScript, or Python)
Download the appropriate template
Install dependencies
Generate an iii-config.yaml configuration file

Terminal output example

$ motia-cli create my-app

  ╭───────────────────────────────────────╮
  │  == Welcome to Motia powered by iii   │
  ╰───────────────────────────────────────╯

  Project folder name: my-app
  Do you have iii installed? (Y/n): Y

  Creating project in ./my-app

  ↓ package.json
  ↓ iii-config.yaml
  ↓ steps/example.step.ts
  ↓ .gitignore

  Installing dependencies...

  ✓ Project created successfully!

  Next steps:
    cd my-app
    iii -c iii-config.yaml

Environment configuration

All CLI commands automatically load environment variables from .env files in your project root.

GitHub token (optional)

When creating projects, you can set a GITHUB_TOKEN to increase API rate limits:

export GITHUB_TOKEN=your_github_token
motia-cli create my-app

This is useful if you encounter rate limit errors when downloading templates.

Next steps

Create command

Learn about project creation and templates

Development commands

Build and run your project locally

Build commands

Create production-ready builds

Quick start guide

Complete tutorial for new projects

TypeScript/JavaScript

Python

CLI

​Installation

​Using Homebrew (macOS/Linux)

​Using shell script

​Verify installation

​Prerequisites

​Available commands

​Standalone CLI (motia-cli)

​Framework commands (motia/motia-iii)

​Python-specific commands

​Quick start

​Terminal output example

​Environment configuration

​GitHub token (optional)

​Next steps