# uip maestro debug

> Upload a local Maestro project to Studio Web and run a server-side debug session with streamed status updates using `uip maestro debug`.

`uip maestro debug` uploads a local Maestro project to **Studio Web** and runs a server-side debug session, streaming per-element status updates back to the console and returning a final status.

## Synopsis

```
uip maestro debug <project-path>
                  [--folder-id <id>]
                  [--poll-interval <ms>]
                  [-i, --inputs <json>]
                  [--login-validity <minutes>]
```

Requires `uip login`. Honors [global options](./global-options.md). Exit codes follow the [standard contract](./exit-codes.md).

## Arguments

- `<project-path>` *(required)* — path to the Maestro project directory. Must contain `project.uiproj`.

## Options

| Option | Default | Description |
|---|---|---|
| `--folder-id <id>` | auto-detected | Orchestrator folder (`OrganizationUnitId`). If omitted, the folder on the current login session is used. Parsed and validated via `parseFolderId`. |
| `--poll-interval <ms>` | `2000` | Polling interval in milliseconds. Must be a positive number. |
| `-i, --inputs <json>` | — | Input arguments as JSON string, or `@path/to/file.json`. |
| `--login-validity <minutes>` | `10` | Minimum minutes before token expiration to trigger an automatic refresh. |

## Behavior

1. Validates login and pulls the organization, tenant, base URL, and auth token from the session.
2. Uploads the project to Studio Web under the target folder.
3. Polls for a final status, emitting per-element status lines like:
   ```
   Status: InProgress (2/5 elements completed)
     v Activity_1 [Completed]
     > Activity_2 [InProgress]
     - Activity_3 [NotStarted]
   ```
4. On incidents during the run, emits a log line.
5. Exits `0` if `finalStatus` is `Completed` or `Successful`; `1` otherwise.

## Examples

```bash
# Debug with auto-detected folder
uip maestro debug ./invoice-orchestration

# Specify folder and inline inputs
uip maestro debug ./invoice-orchestration --folder-id 2553016 \
  --inputs '{"amount":100,"customer":"Acme"}'

# Inputs from a file
uip maestro debug ./invoice-orchestration --inputs @inputs.json
```

## Data shape (--output json)

```json
{
  "Code": "MaestroDebug",
  "Data": {
    "jobKey":      "b2c3d4e5-0000-0000-0000-000000000001",
    "instanceId":  "c3d4e5f6-0000-0000-0000-000000000001",
    "runId":       "d4e5f6a7-0000-0000-0000-000000000001",
    "finalStatus": "Completed",
    "solutionId":  "e5f6a7b8-0000-0000-0000-000000000001",
    "elementExecutions": [
      { "elementId": "Activity_1", "status": "Completed" }
    ]
  }
}
```

## See also

- [`uip maestro process run`](./uip-maestro-process.md#uip-maestro-process-run) — run a *published* process
- [`uip maestro job traces`](./uip-maestro-job.md#uip-maestro-job-traces) — stream traces for an already-started job
- [Authentication](./authentication.md)
- [Maestro overview](./uip-maestro.md)