Command Line Interface (CLI)

Motia provides a powerful Command Line Interface (CLI) to help you manage your projects and workflows. The CLI offers various commands for creating projects, generating steps, managing state, and more.

Installation

The Motia CLI is automatically installed when you install the motia package. You can use it by running npx motia followed by the desired command.

Commands

create

Create a new Motia project.

npx motia@latest create [project-name] [options]

Arguments:

• [project-name] (optional): The name for your project folder. If not provided, you will be prompted to enter it. Use . or ./ to create it in the current directory.

Options:

• --template <template-name> (optional): The template to use for your project. If not provided, you will be prompted to select one interactively.
• --skip-redis (optional): Skip the embedded Redis binary installation. Use this when you have your own Redis instance or want to configure external Redis.

Available Templates:

Motia provides several project templates to help you get started quickly:

Examples:

Create a TypeScript starter project:

npx motia@latest create my-app --template starter-typescript

Create a Python tutorial project:

npx motia@latest create my-tutorial --template motia-tutorial-python

Use interactive mode (no template specified):

npx motia@latest create
# You'll be prompted to select a template from the list above

Create project without embedded Redis (use your own Redis):

npx motia@latest create my-app --skip-redis

build

Build your project, generating zip files for each step and creating a configuration file.

npx motia build

This command:

1. Compiles all your steps (both Node.js and Python)
2. Bundles each step into a zip file
3. Generates a motia.steps.json configuration file in the dist directory
4. Organizes the output in the dist directory

deploy

Deploy your built steps to the Motia deployment service.

motia cloud deploy --api-key <api-key> --version-name <version> [options]

Options:

• -k, --api-key <key> (required): Your API key for authentication
• -n, --project-name <name>: Project name (used when creating a new project)
• -s, --environment-id <id>: Environment ID (can also be set via MOTIA_ENVIRONMENT_ID env var)
• --environment-name <name>: Environment name (used when creating a new environment)
• -v, --version-name <version> (required): The version to deploy
• -d, --version-description <description>: The description of the version
• -e, --env-file <path>: Path to environment file

Example:

motia cloud deploy --api-key your-api-key-here --version-name 1.2.3 --environment-id env-uuid

The deployment process:

1. Build your project
2. Uploads each zip file individually with its path information
3. Starts the deployment process on the server

dev

Start the development server with hot reload and Workbench.

npx motia dev [options]

Options:

• -p, --port <port>: The port to run the server on (default: 3000).
• -H, --host [host]: The host address for the server (default: localhost).
• -d, --debug: Enable debug logging.
• -m, --mermaid: Enable Mermaid diagram generation.
• --motia-dir <path>: Custom path for .motia folder.

start

Start the production server without hot reload. Workbench is included by default (can be disabled via MOTIA_DOCKER_DISABLE_WORKBENCH environment variable).

npx motia start [options]

Options:

• -p, --port <port>: The port to run the server on (default: 3000).
• -H, --host [host]: The host address for the server (default: localhost).
• -d, --debug: Enable debug logging.
• --motia-dir <path>: Custom path for .motia folder.

Example:

# Start production server on port 8080
npx motia start --port 8080
 
# Start on a specific host
npx motia start --host 0.0.0.0 --port 3000
 
# Start without Workbench
MOTIA_DOCKER_DISABLE_WORKBENCH=true npx motia start

get-config

Get the generated config for your project.

npx motia get-config [options]

Options:

• -o, --output <path>: Path to write the generated config file.

emit

Emit an event to the Motia server.

npx motia emit [options]

Options:

• --topic <topic> (required): Event topic/type to emit.
• --message <message> (required): Event payload as a JSON string.
• -p, --port <number>: Port number (default: 3000).

generate

Generate Motia resources.

generate step

Create a new step with interactive prompts.

npx motia generate step [options]

Options:

• -d, --dir <step file path>: The path relative to the src directory to create the step file.

generate openapi

Generate OpenAPI spec for your project.

npx motia generate openapi [options]

Options:

• -t, --title <tile of the document>: Title for the OpenAPI document. Defaults to project name from package.json.
• -v, --version <version of the document>: Version of the OpenAPI document. Defaults to 1.0.0.
• -o, --output <output file name / path>: The file name and path relative to root to create the openapi file. Defaults to openapi.json at the root.

state

Manage application state.

state list

List the current file state.

npx motia state list

Debugging

You can enable debug logging by passing the -d or --debug flag to the dev command:

npx motia dev --debug

This will set the LOG_LEVEL environment variable to 'debug', providing more detailed logging output.

docker

Tools to help you setup your Motia project with docker and run it inside a container.

docker setup

Setup your Motia project for Docker

npx motia docker setup

docker build

Build your Motia project Docker image

npx motia docker build

Options:

• --project-name <project name> (required): The name of your project.

docker run

Run your Motia project inside a container

npx motia docker run

Options:

• --port <number>: Port number (default: 3000).
• --project-name <project name> (required): The name of your project.
• --skip-build: Skip building the Docker image and used the last built image.

Next Steps

• Explore the Core Concepts to learn more about Steps, Flows, Events, and Topics.
• Check out the Examples for common patterns and use cases.
• Join our Community for help and discussions.