Quick Start

1. Install iii

The iii engine is the runtime that powers Motia. Install it with:

curl -fsSL https://install.iii.dev/iii/main/install.sh | sh

Verify the installation:

iii -v

2. Install motia-cli

Install the Motia project scaffolding CLI:

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

Or via Homebrew:

brew tap MotiaDev/tap
brew install motia-cli

3. Create Your Project

Run the create command and follow the prompts to choose your project name and language:

motia-cli create my-project

Select your preferred language when prompted:

• Node.js — TypeScript/Node.js only (no Python required)
• Python — Python only (no npm required)
• Mixed — Node.js handles HTTP APIs, Python handles background processing; both share the same iii infrastructure

4. Start the Project

The iii-config.yaml in the project tells the iii engine how to run Motia — starting iii starts everything.

cd my-project
iii -c iii-config.yaml

5. Run Your First Flow

This example is a ticketing system for user issues. Try it out:

# Create a ticket
curl -X POST http://localhost:3111/tickets \
  -H "Content-Type: application/json" \
  -d '{"title":"Login issue","description":"User is having trouble creating an account","priority":"high","customerEmail":"user@example.com"}' | jq

# List all tickets
curl http://localhost:3111/tickets | jq

6. What Just Happened?

When you created a ticket, here is what Motia did behind the scenes:

1. HTTP trigger — The POST /tickets request hit a Step with an http trigger, which validated the input and stored the ticket in state.
2. Queue trigger — That Step enqueued a message to a topic. Another Step with a queue trigger picked it up and processed the ticket asynchronously (e.g., classification, notification).
3. State — The ticket data was persisted using Motia's built-in key-value state, so the GET /tickets endpoint could retrieve it.

7. Try the iii Console

The iii console gives you complete observability of your Motia project — flow diagrams, real-time logs, state inspection, and stream monitoring. Install and start it in a new terminal:

curl -fsSL https://install.iii.dev/console/main/install.sh | sh
iii-console --enable-flow

Then open your browser to: http://localhost:3113/

The console dashboard gives you a system overview of your running application:

Navigate to the Flow tab to see your Steps connected as a visual workflow:

Manual Setup (Alternative)

If you prefer to clone the example repository directly instead of using motia-cli:

git clone https://github.com/MotiaDev/motia-iii-example.git
cd motia-iii-example/nodejs
npm install

Next Steps

You have successfully run your first Motia workflow. Here is where to go next: