CLI overview

The mayura command ships inside the mayura npm package. You use it to create projects from starters and templates, to run your application during development and in production, and to operate a running Mayura server from a terminal or a script.

npx mayura init

In a terminal, mayura init with no options opens a short wizard. Everything else is driven by flags, so the same commands work in scripts and CI.

#Installing and running

You do not need to install anything globally. There are two common ways to run the CLI:

• Before you have a project, run it with npx, which fetches the mayura package on demand:

  bashCopy

  npx mayura starters

• Inside a project, add mayura as a dependency. Every project created by mayura init already has it, pinned to the exact version of the CLI that created it. Run the command through npx or from your package.json scripts:

  bashCopy

  npm install mayura
  npx mayura --version

  The starters' scripts call it this way, for example "dev": "mayura dev" and "serve": "mayura serve --app dist/src/app.js".

The CLI needs Node.js 22 (22.12 or later) or 24 (24.14.1 or later). See Support.

#Commands

mayura --help groups the commands like this:

Options take the form --name value, or just --name for switches such as --apply. An unknown option, or the same option given twice, is an error.

#Help and version

mayura --help
mayura init --help
mayura --version

--help (or -h) shows the command list and wins anywhere on the line, so mayura init --help prints help instead of an argument error. mayura help does the same. Running mayura with no command in a terminal also prints help.

--version (or -v, or mayura version) prints the version as plain text, so scripts can read it. Add --json to get it as a JSON document instead.

#Readable and JSON output

The CLI picks its output format from where the output goes:

• In a terminal, results are readable: coloured statuses (✔ succeeded, ● waiting, ✖ failed), wrapped descriptions, and the next command or flag to use.
• When output is piped or redirected, every command prints one JSON document instead. Scripts and CI can parse it directly.
• With --json, the CLI always prints JSON, even in a terminal.

mayura templates --json
mayura starters | jq -r '.starters[].name'

Every JSON document has a status field. Most commands report succeeded; init without --apply reports planned, migrate reports migrated, serve, worker and dev report stopped when they exit, and a fleet-sweep that did not finish reports incomplete.

Colour follows the usual conventions: it is off when NO_COLOR is set to any non-empty value or TERM=dumb, and on when FORCE_COLOR is set to anything other than 0. Colour is never written into JSON output.

#Exit codes and errors

Errors go to stderr. In a terminal they read like this:

✖ Unknown template; run mayura templates. (INVALID_INPUT)

When stderr is not a terminal, or with --json, the error is a JSON document:

{"status":"failed","error":{"code":"INVALID_INPUT","message":"Unknown command. Run mayura --help to see the commands."}}

The code is one of Mayura's error codes (see Outcomes): INVALID_INPUT for a usage problem the CLI found, INVALID_CONFIG for a bad file or setting, PERMISSION_DENIED, NOT_FOUND, CONFLICT, TIMEOUT and so on for server commands. Messages are fixed, safe text. The CLI never echoes an unknown command or argument back, because it might be a credential pasted in the wrong place.

#Good to know

• The CLI never prompts for a server token. Authenticated commands read it only from stdin (--token-stdin); see Operate a server.
• serve, worker and migrate import only the one module you name with --app. Listing and inspecting a project never runs your code.
• Everything the commands do is also available as functions from mayura/cli, for example planProject, inspectWorkflows and defineMayuraApplication. See Entry points.

#Related

• Create a project
• Develop with mayura dev
• Serve, worker and migrate
• Operate a server
• Quickstart