Development commands

Development commands help you build, run, and iterate on your Motia project locally with automatic type generation and optional file watching.

motia dev (JavaScript/TypeScript)

Builds your project in development mode with full type generation support.

Usage

motia dev

What it does

Generates TypeScript types - Automatically creates types.d.ts from your steps and streams
Bundles your code - Uses esbuild to create dist/index-dev.js
Preserves external packages - All dependencies remain external for faster rebuilds
Includes source maps - Full debugging support in development

Output

$ motia dev

Generating types...
✓ types.d.ts created

Building for development...
✓ dist/index-dev.js [42.5 KB]

Done in 234ms

Configuration

The dev command automatically:

Sets platform to node
Targets Node.js 22+
Uses ESM format
Bundles code with source maps
Keeps all npm packages external

Running the built output

After building, run your project with the iii engine:

iii -c iii-config.yaml

The iii engine will load the development build and start your steps.

motia typegen (JavaScript/TypeScript)

Generates TypeScript type definitions from your steps and streams.

Usage

motia typegen [options]

Options

Option	Alias	Description	Default
`--output <path>`	`-o`	Output file path	`types.d.ts`
`--watch`	`-w`	Watch for file changes	`false`

Examples

Basic type generation

motia typegen

Output:

✓ types.d.ts created

Custom output path

motia typegen --output src/generated/types.d.ts

Watch mode

motia typegen --watch

Output:

✓ types.d.ts created
Watching for changes...

[File changed: steps/new-step.step.ts]
✓ types.d.ts updated

Generated types structure

The typegen command analyzes your steps and streams to generate:

// types.d.ts
declare module 'motia' {
  export interface StepContext {
    enqueue: (data: EnqueueData) => Promise<void>
    logger: Logger
  }

  export interface EnqueueData {
    topic: 'message.sent' | 'user.created'
    data: any
  }
}

motia run (Python)

Discovers and runs Python steps and streams.

Usage

motia run [options]

Options

Option	Alias	Description	Default
`--dir <directory>`	`-d`	Directory containing step files	`steps`
`--verbose`	`-v`	Enable verbose logging	`false`

Examples

Basic run

motia run

Output:

2026-02-28 10:30:15 [INFO] motia.cli: Found 3 step(s) and 1 stream(s)
2026-02-28 10:30:15 [DEBUG] motia.cli: Loading step: steps/send_message_step.py
2026-02-28 10:30:15 [DEBUG] motia.cli: Loading step: steps/process_message_step.py
2026-02-28 10:30:15 [INFO] motia.cli: All steps loaded. Connecting...
2026-02-28 10:30:16 [INFO] motia.cli: Connected. Waiting for events...

Custom directory

motia run --dir src/steps

Verbose logging

motia run --verbose

Output:

2026-02-28 10:30:15 [DEBUG] motia.cli: Discovering steps in: steps
2026-02-28 10:30:15 [DEBUG] motia.cli: Found step file: steps/example_step.py
2026-02-28 10:30:15 [DEBUG] motia.cli: Loading module from: steps/example_step.py
2026-02-28 10:30:15 [DEBUG] motia.cli: Registered step: ExampleStep
2026-02-28 10:30:15 [INFO] motia.cli: All steps loaded. Connecting...

Step discovery

The run command automatically discovers:

All *_step.py files in the specified directory
All *_stream.py files for streaming configuration
Includes src/ directory if it exists

motia dev (Python)

Runs Python steps in development mode with optional file watching.

Usage

motia dev [options]

Options

Option	Alias	Description	Default
`--dir <directory>`	`-d`	Directory containing step files	`steps`
`--watch`	`-w`	Watch for file changes	`false`
`--verbose`	`-v`	Enable verbose logging	`false`

Examples

Development mode

motia dev

Watch mode

motia dev --watch

Output:

2026-02-28 10:30:15 [INFO] motia.cli: Watching for changes...
2026-02-28 10:30:15 [INFO] motia.cli: Found 2 step(s) and 0 stream(s)
2026-02-28 10:30:15 [INFO] motia.cli: Connected. Waiting for events...

[File changed: steps/example_step.py]
[Restarting...]

Watch mode requires the watchfiles package. Install it with:

pip install watchfiles

If not available, the command runs without watching.

Auto-restart behavior

When a file changes in watch mode:

The process detects the change
Automatically restarts using os.execv()
Reloads all steps and streams
Reconnects to the iii engine

Environment variables

All development commands automatically load .env files:

# .env
III_HOST=localhost
III_PORT=3000
LOG_LEVEL=debug

Your steps can access these via process.env (JavaScript/TypeScript) or os.environ (Python).

Development workflow

Typical development workflow with Motia:

1. Start the iii engine

iii -c iii-config.yaml

2. Build in development mode

JavaScript/TypeScript:

motia dev

Python:

motia dev --watch

3. Make changes to your steps

Edit files in the steps/ directory.

4. Rebuild (JavaScript/TypeScript only)

motia dev

Python watch mode auto-restarts on changes.

5. Test your changes

Use the iii Console or make HTTP requests to your steps:

curl -X POST http://localhost:3000/messages \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, Motia!"}'

Performance optimization

JavaScript/TypeScript builds

Development builds are optimized for speed:

External packages aren’t bundled (faster rebuilds)
Source maps included for debugging
No minification (faster builds)

Production builds optimize for deployment:

All dependencies bundled
Code minified and tree-shaken
Source maps for error tracking

Python watch mode

For large projects, specify only the directories you’re working on:

motia dev --dir src/api --watch

Troubleshooting

Type generation fails

Type generation failed: Cannot find module 'steps/example.step.ts'

Solution: Ensure all step files have valid exports:

export const config = { /* ... */ }
export const handler = async (input, ctx) => { /* ... */ }

Build fails with import errors

Error: Could not resolve "some-package"

Solution: Install missing dependencies:

npm install some-package

Python watch mode not working

[WARNING] watchfiles not available; running without watch mode

Solution: Install watchfiles:

pip install watchfiles

Connection refused

Error: connect ECONNREFUSED 127.0.0.1:3000

Solution: Start the iii engine first:

iii -c iii-config.yaml

Next steps

Build commands

Create production-ready builds

Defining steps

Learn how to create Motia steps

Triggers

Configure HTTP, queue, cron, and stream triggers

iii Console

Monitor your application in development

TypeScript/JavaScript

Python

CLI

​motia dev (JavaScript/TypeScript)

​Usage

​What it does

​Output

​Configuration

​Running the built output

​motia typegen (JavaScript/TypeScript)

​Usage

​Options

​Examples

​Basic type generation

​Custom output path

​Watch mode

​Generated types structure

​motia run (Python)

​Usage

​Options

​Examples

​Basic run

​Custom directory

​Verbose logging

​Step discovery

​motia dev (Python)

​Usage

​Options

​Examples

​Development mode

​Watch mode

​Auto-restart behavior

​Environment variables

​Development workflow

​1. Start the iii engine

​2. Build in development mode

​3. Make changes to your steps

​4. Rebuild (JavaScript/TypeScript only)

​5. Test your changes

​Performance optimization

​JavaScript/TypeScript builds

​Python watch mode

​Troubleshooting

​Type generation fails

​Build fails with import errors

​Python watch mode not working

​Connection refused

​Next steps

Build commands

Defining steps

Triggers

iii Console

Build docs developers (and LLMs) love

motia dev (JavaScript/TypeScript)

Usage

What it does

Output

Configuration

Running the built output

motia typegen (JavaScript/TypeScript)

Usage

Options

Examples

Basic type generation

Custom output path

Watch mode

Generated types structure

motia run (Python)

Usage

Options

Examples

Basic run

Custom directory

Verbose logging

Step discovery

motia dev (Python)

Usage

Options

Examples

Development mode

Watch mode

Auto-restart behavior

Environment variables

Development workflow

1. Start the iii engine

2. Build in development mode

3. Make changes to your steps

4. Rebuild (JavaScript/TypeScript only)

5. Test your changes

Performance optimization

JavaScript/TypeScript builds

Python watch mode

Troubleshooting

Type generation fails

Build fails with import errors

Python watch mode not working

Connection refused

Next steps