npm package: @forgecart/cli
Description: CLI tool for deploying applications to ForgeCart
Author: ForgeCart
Latest version: 1.1.0

# @forgecart/cli

CLI tool for deploying applications to ForgeCart's PaaS platform.

## Installation

```bash
npm install -g @forgecart/cli
```

## Quick Start

1. **Create a new project:**
   ```bash
   forgecart init my-store
   ```

2. **Deploy:**
   ```bash
   cd my-store
   forgecart deploy
   ```

## Commands

### `forgecart init [name]`

Create a new ForgeCart project.

Options:
- `-t, --token <token>` - ForgeCart channel token
- `-a, --application` - Include NestJS backend application
- `--api-url <url>` - ForgeCart API URL (default: https://api.forgecart.com)

### `forgecart init:application`

Add a NestJS backend application to an existing project.

### `forgecart deploy`

Deploy the current application.

Options:
- `--skip-build` - Skip the build step

### `forgecart list`

List all deployments for the current channel.

### `forgecart status [type]`

Show detailed deployment status.

Arguments:
- `type` - Deployment type: `storefront` or `application`

### `forgecart logs [type]`

View deployment logs.

Arguments:
- `type` - Deployment type (default: `storefront`)

Options:
- `-f, --follow` - Follow log output
- `-n, --lines <number>` - Number of lines to show (default: 100)

### `forgecart delete <type>`

Delete a deployment.

Arguments:
- `type` - Deployment type: `storefront` or `application`

Options:
- `-f, --force` - Skip confirmation prompt

### `forgecart scale <type> <instances>`

Scale a deployment.

Arguments:
- `type` - Deployment type: `storefront` or `application`
- `instances` - Number of instances (0-10)

### `forgecart env`

Manage environment variables.

Subcommands:
- `forgecart env get <type>` - Get environment variables
- `forgecart env set <type> <key> <value>` - Set an environment variable
- `forgecart env unset <type> <key>` - Remove an environment variable

### `forgecart whoami`

Show current channel information.

## Project Structure

After running `forgecart init`, your project will have the following structure:

```
my-store/
├── .forgecart/
│   └── config.json           # ForgeCart configuration
├── nx.json                   # NX workspace configuration
├── package.json              # Root package.json
├── tsconfig.base.json        # TypeScript configuration
├── apps/
│   ├── storefront/           # Next.js frontend (required)
│   │   ├── src/
│   │   │   ├── lib/
│   │   │   │   └── forgecart.ts   # SDK client
│   │   │   └── app/
│   │   │       └── products/
│   │   │           └── page.tsx   # Example products page
│   │   ├── Procfile               # Deployment configuration
│   │   └── .forgecartignore       # Files to exclude from deploy
│   └── application/          # NestJS backend (optional)
│       ├── src/
│       │   └── services/
│       │       └── price-fetcher.service.ts  # SDK example
│       ├── Procfile               # Deployment configuration
│       └── .forgecartignore       # Files to exclude from deploy
└── libs/                     # Shared libraries (optional)
```

## Configuration

The CLI stores configuration in `.forgecart/config.json`:

```json
{
  "version": "1.0",
  "channelToken": "your-channel-token",
  "apiUrl": "https://api.forgecart.com",
  "hasApplication": false,
  "storefrontPath": "apps/storefront",
  "applicationPath": "apps/application"
}
```

## Environment Variables

Set environment variables for your deployments:

```bash
# Set SDK credentials
forgecart env set storefront FORGECART_CHANNEL_TOKEN your-token
forgecart env set storefront FORGECART_API_URL https://api.forgecart.com

# View all environment variables
forgecart env get storefront

# Remove an environment variable
forgecart env unset storefront MY_VAR
```

## Deployment Workflow

1. Make changes to your code
2. Run `forgecart deploy` from your project root or app directory
3. The CLI will:
   - Build your application using NX
   - Create a deployment archive
   - Upload and deploy to ForgeCart
   - Wait for the deployment to be ready
4. View your live application at the provided URL

## Requirements

- Node.js >= 18.0.0
- npm or yarn
- A ForgeCart account with a valid channel token

## License

MIT