> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stac.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Stac CLI

> Build, deploy, and manage Server-Driven UI projects with the Stac CLI.

## Installation

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/StacDev/install/main/install.sh | bash
    ```

    Verify installation:

    ```bash theme={null}
    stac --version
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    irm https://raw.githubusercontent.com/StacDev/install/main/install.ps1 | iex
    ```

    Verify installation:

    ```powershell theme={null}
    stac --version
    ```
  </Tab>
</Tabs>

## Available Commands

| Command          | Description                        | Requires Auth |
| ---------------- | ---------------------------------- | ------------- |
| `login`          | Authenticate with Google OAuth     | No            |
| `logout`         | Clear stored authentication tokens | No            |
| `status`         | Show authentication status         | No            |
| `init`           | Initialize Stac in project         | Yes           |
| `build`          | Convert Dart widgets to JSON       | No            |
| `deploy`         | Build and deploy to Stac Cloud     | Yes           |
| `project list`   | List all cloud projects            | Yes           |
| `project create` | Create new cloud project           | Yes           |

## Authentication

Before using most CLI commands, you'll need to authenticate with Stac Cloud.

### Login

This opens your browser for OAuth authentication. Your credentials are securely stored locally.

```bash theme={null}
stac login
```

### Check Status

```bash theme={null}
stac status
```

### Logout

```bash theme={null}
stac logout
```

## Initialize Stac

Use this to set up Stac in an existing Flutter/Dart project. It links your local app to a Stac Cloud project and scaffolds required files.

```bash theme={null}
stac init
```

#### What it does

* Creates `stac/` folder for Stac DSL widgets
* Adds `lib/default_stac_options.dart` with your `StacOptions` (e.g., `projectId`)
* Updates `pubspec.yaml` with `stac` and related dependencies
* Optionally links to an existing Stac Cloud project

#### Generated files

```bash theme={null}
|- Flutter project
├── lib/
│   ├── default_stac_options.dart
│   └── main.dart
├── stac/
│   └── stac_widget.dart
└── pubspec.yaml
```

### Convert Dart to JSON

Build all widgets in current project:

```bash theme={null}
stac build
```

Build specific project directory:

```bash theme={null}
stac build --project /path/to/project
```

Build with validation (enabled by default):

```bash theme={null}
stac build --validate
```

Build with verbose output:

```bash theme={null}
stac build --verbose
```

#### Build Options

| Option          | Description                | Default           |
| --------------- | -------------------------- | ----------------- |
| `-p, --project` | Project directory path     | Current directory |
| `--validate`    | Validate generated JSON    | `true`            |
| `-v, --verbose` | Show detailed build output | `false`           |

The build command converts Stac widget definitions from the `stac/` folder into JSON format in the `build/` folder.

### Deploy to Stac Cloud

Build and deploy to Stac Cloud:

```bash theme={null}
stac deploy
```

Deploy specific project directory:

```bash theme={null}
stac deploy --project /path/to/project
```

Skip build and deploy existing files:

```bash theme={null}
stac deploy --skip-build
```

Deploy with verbose output:

```bash theme={null}
stac deploy --verbose
```

### Deployment Options

| Option          | Description                     | Default           |
| --------------- | ------------------------------- | ----------------- |
| `-p, --project` | Project directory path          | Current directory |
| `--skip-build`  | Skip building before deployment | `false`           |
| `-v, --verbose` | Show detailed deployment output | `false`           |

<Note>
  By default, `stac deploy` automatically runs `stac build` before deploying. Use `--skip-build` to deploy existing build files without rebuilding.
</Note>

### List Projects

List all your Stac Cloud projects:

```bash theme={null}
stac project list
```

Output as JSON format:

```bash theme={null}
stac project list --json
```

The list command shows:

* Project name and ID
* Project description
* Created and updated timestamps

### Create New Project

```bash theme={null}
stac project create --name "My App" --description "My SDUI app"
```

Short form:

```bash theme={null}
stac project create -n "My App" -d "My SDUI app"
```

After creating a project, run `stac init` to initialize it locally.

### Typical Workflow

1. Authenticate with Stac Cloud (one-time):

```bash theme={null}
stac login
```

2. List available projects:

```bash theme={null}
stac project list
```

3. Initialize a project in your Flutter/Dart app:

```bash theme={null}
cd your-flutter-project
stac init
```

4. Create your widget definitions in the `stac/` folder, then deploy:

```bash theme={null}
stac deploy
```

## Command Reference

### Global Options

| Option          | Description                    |
| --------------- | ------------------------------ |
| `-v, --verbose` | Show additional command output |
| `--version`     | Print tool version             |
| `--help`        | Print usage information        |