npm package: @motiadev/cloud
Description: Motia Cloud
Author: Motia
Latest version: 1.0.0-alpha.26

# Motia Cloud CLI

A command-line interface for managing MotiaCloud projects and deployments.

## Installation

```bash
npm install -g @motiadev/cloud
```

## Environment Variables

The CLI supports the following environment variables:

- `MOTIA_API_KEY`: Your Motia Cloud API key (can be used instead of providing the `--api-key` option)

## Commands

### Project Management

You can create multiple projects in Motia Cloud, it represents an application or a service under your organization.

#### Initialize a Project

```bash
motiacloud init [options]
```

Options:

- `-k, --api-key <api key>`: API key for authentication (required)
- `-p, --project <project id>`: The project ID of an existing Motia Cloud project
- `-n, --name <project name>`: The name for your Motia Cloud project
- `-d, --description <description>`: Description of the Motia Cloud project

#### List Projects

```bash
motiacloud project ls [options]
```

Options:

- `-k, --api-key <api key>`: API key for authentication (required)

### Environment Management

Underneath each project, you can create multiple environments, it represents a version environment.

**Examples are:** staging, dev, production, sandbox, preview, etc.

#### Create a Environment

```bash
motiacloud environment create [options]
```

Options:

- `-k, --api-key <api key>`: API key for authentication (required)
- `-n, --name <environment name>`: The name for your version environment
- `-d, --description <description>`: Description of the version environment

#### Select a Environment

```bash
motiacloud environment select [options]
```

Options:

- `-k, --api-key <api key>`: API key for authentication (required)
- `-n, --name <environment name>`: The name of the environment to select

#### List Environments

```bash
motiacloud environment list [options]
```

Options:

- `-k, --api-key <api key>`: API key for authentication (required)

#### Update Environment Version

You can promote a version to a environment, all traffic will be routed to the new version.

```bash
motiacloud environment update [options]
```

Options:

- `-k, --api-key <api key>`: API key for authentication (required)
- `-v, --version <version>`: The version to promote (required)

### Version

#### Build Project

This is just to test the build process, it will not deploy anything.

```bash
motiacloud build
```

#### Deploy Project

This command builds the project and then deploys it to the selected environment. You need to specify a new version for the version.

Each version has unique version, specifying an existing version will fail.

```bash
motiacloud deploy [options]
```

Options:

- `-k, --api-key <key>`: The API key for authentication (required)
- `-v, --version <version>`: The version to deploy (required)
- `-p, --project-id <id>`: Override the selected project
- `-s, --environment-id <id>`: Override the selected environment
- `-e, --env-file <path>`: Path to environment file

#### Get Logs

Will list latest logs from the selected environment. This includes all versions deployed to the environment.
You should see the version that generated the log on each log line. Details are not included
by default, use the `--include-details` flag to include them.

```bash
motiacloud logs [options]
```

Options:

- `-k, --api-key <key>`: The API key for authentication (required)
- `-s, --environment <environment>`: The environment to get logs from
- `-i, --include-details`: Include details in the logs

## Configuration

The CLI stores project configuration in a local config file. We recommend pushing this file to your version control system. This includes:

- Project ID
- Project name
- Project description
- Selected environment

## Error Handling

The CLI provides detailed error messages and status updates during operations. If an error occurs:

1. The operation will be terminated
2. A descriptive error message will be displayed
3. The process will exit with a non-zero status code

## Best Practices

1. Always use the `--api-key` option or set the `MOTIA_API_KEY` environment variable.
2. Select a environment before deploying.
3. Use semantic versioning for your versions.
4. Keep your environment files secure and never commit them to version control, make sure to add the file name to your `.gitignore` file.