### Recommended Setup and Development Start

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Steps for new developers to clone the repository, set up the monorepo, and start development servers.

```bash
git clone git@github.com:unraid/api.git
just setup
pnpm install
pnpm dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/unraid/api/blob/main/web/README.md

Run this command to install project dependencies.

```bash
npm i
```

--------------------------------

### Start UI Component Development Server

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Navigate to the unraid-ui directory and run this command to start only the UI components development server.

```bash
cd unraid-ui
pnpm dev
```

--------------------------------

### Start Web Development Server

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Navigate to the web directory and run this command to start only the web components development server.

```bash
cd web
pnpm dev
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/unraid/api/blob/main/unraid-ui/README.md

Install all project dependencies required for local development of the Unraid UI library.

```bash
npm install
```

--------------------------------

### Start All Development Servers

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Run this command to start all development servers concurrently for the API, web components, and UI components.

```bash
pnpm dev
```

--------------------------------

### Build Dependencies and Start Docker Container

Source: https://github.com/unraid/api/blob/main/plugin/README.md

Combines building the Docker container and starting it, including building necessary dependencies. This is a convenient command for setting up the development environment.

```bash
pnpm docker:build-and-run
```

--------------------------------

### Start API Development Server

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Navigate to the API directory and run this command to start only the API development server.

```bash
cd api
pnpm dev
```

--------------------------------

### Install Shadcn Component

Source: https://github.com/unraid/api/blob/main/unraid-ui/README.md

Use the Shadcn CLI to install a new component into the project. Replace '[component-name]' with the desired component.

```bash
npx shadcn-vue@latest add [component-name]
```

--------------------------------

### GraphQL Mutation to Start a Virtual Machine

Source: https://context7.com/unraid/api/llms.txt

Start a specified virtual machine using its ID.

```graphql
# Start a VM
mutation StartVM {
  vm {
    start(id: "server123:vm-uuid-here")
  }
}
```

--------------------------------

### Install Dependencies

Source: https://github.com/unraid/api/blob/main/AGENTS.md

Installs all project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Verify Installations and Versions

Source: https://github.com/unraid/api/blob/main/readme.md

Check that Node.js, pnpm, rclone, jq, and Docker are installed and meet the required versions.

```bash
node --version
```

```bash
pnpm --version
```

```bash
rclone version
```

```bash
jq --version
```

```bash
docker --version
```

--------------------------------

### Start Docker Container for API

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Navigate to the API directory and run this command to start the Docker container.

```bash
cd api
pnpm container:start
```

--------------------------------

### Build and Start Development Docker Container

Source: https://github.com/unraid/api/blob/main/api/docs/developer/development.md

Run these commands to set up a development environment and start an interactive shell within a Docker container.

```bash
npm run build:docker
npm run start:ddev
```

--------------------------------

### Verify Prerequisites

Source: https://github.com/unraid/api/blob/main/readme.md

This command verifies the installation of necessary dependencies for the Unraid API project.

```bash
bash
```

--------------------------------

### Enable GraphQL Sandbox

Source: https://github.com/unraid/api/blob/main/AGENTS.md

Starts the developer tools with the GraphQL sandbox enabled.

```bash
unraid-api developer --sandbox true
```

--------------------------------

### Start Storybook Development Server

Source: https://github.com/unraid/api/blob/main/unraid-ui/README.md

Start the Storybook development server to view and test UI components in isolation. Accessible at http://localhost:6006.

```bash
npm run storybook
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/unraid/api/blob/main/readme.md

Clone the Unraid API repository and install all monorepo dependencies using pnpm. The install script verifies required dependencies and versions.

```bash
git clone git@github.com:unraid/api.git
cd api
pnpm install
```

--------------------------------

### Install Peer Dependencies

Source: https://github.com/unraid/api/blob/main/unraid-ui/README.md

Install Vue 3 and Tailwind CSS, which are required peer dependencies for the Unraid UI library.

```bash
npm install vue@^3.3.0 tailwindcss@^3.0.0
```

--------------------------------

### Unraid API CLI Help

Source: https://github.com/unraid/api/blob/main/api/README.md

Displays the usage guide and available commands for the Unraid API CLI. Use this to understand the basic structure and options.

```bash
root@Devon:~# unraid-api 

Unraid API

  Thanks for using the official Unraid API

Usage:

  $ unraid-api command <options>

Commands:

  start/stop/restart/version/status/report/switch-env

Options:

  -h, --help                                                   Prints this usage guide.
  -d, --debug                                                  Enabled debug mode.
  -p, --port string                                            Set the graphql port.
  --environment production/staging/development                 Set the working environment.
  --log-level ALL/TRACE/DEBUG/INFO/WARN/ERROR/FATAL/MARK/OFF   Set the log level.

  Copyright © 2024 Lime Technology, Inc.


```

--------------------------------

### Run Individual Development Servers

Source: https://github.com/unraid/api/blob/main/readme.md

Start either the API server (GraphQL backend) or the Web interface (Nuxt frontend) development server individually.

```bash
cd api && pnpm dev
cd web && pnpm dev
```

--------------------------------

### GraphQL Mutation to Start a Docker Container

Source: https://context7.com/unraid/api/llms.txt

Start a specified Docker container using its ID.

```graphql
# Start a container
mutation StartContainer {
  docker {
    start(id: "server123:abc123def456") {
      id
      state
      status
    }
  }
}
```

--------------------------------

### GraphQL Welcome Response

Source: https://github.com/unraid/api/blob/main/api/docs/developer/development.md

Example of a successful response from the GraphQL welcome query.

```json
{
    "data": {
        "welcome": {
            "message": "Welcome root to this Unraid 6.10.0 server"
        }
    }
}
```

--------------------------------

### Example Migration: API Key Resolver

Source: https://github.com/unraid/api/blob/main/api/src/unraid-api/graph/README.md

Illustrates the files involved in migrating a resolver, including model definitions, resolver implementation, and module configuration.

```typescript
api-key.model.ts: Contains the model classes for the API Key Resolver
```

```typescript
api-key.resolver.ts: Contains the resolver implementation using the model classes
```

```typescript
api-key.module.ts: Contains the module configuration for the API Key Resolver
```

--------------------------------

### Build and Run Plugin with Docker

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

This command builds all dependencies (API, web) and then starts the Docker container for the plugin. Further build commands may be needed inside the container.

```bash
cd plugin
pnpm run docker:build-and-run
# Then inside the container:
pnpm build
```

--------------------------------

### Virtual Machine Management

Source: https://context7.com/unraid/api/llms.txt

Control libvirt-based virtual machines with start, stop, pause, and state queries.

```APIDOC
## Virtual Machine Management

### Description
Control libvirt-based virtual machines with start, stop, pause, and state queries.

### Method
POST

### Endpoint
`/graphql`

### Parameters
#### Request Body
- **query** (string) - Required - The GraphQL query string.
- **mutation** (string) - Required - The GraphQL mutation string.

### Request Example (List VMs)
```graphql
query GetVMs {
  vms {
    domains {
      id
      name
      state
    }
  }
}
```

### Request Example (Start VM)
```graphql
mutation StartVM {
  vm {
    start(id: "server123:vm-uuid-here")
  }
}
```

### Request Example (Stop VM)
```graphql
mutation StopVM {
  vm {
    stop(id: "server123:vm-uuid-here")
  }
}
```

### Request Example (Force Stop VM)
```graphql
mutation ForceStopVM {
  vm {
    forceStop(id: "server123:vm-uuid-here")
  }
}
```

### Request Example (Pause VM)
```graphql
mutation PauseVM {
  vm {
    pause(id: "server123:vm-uuid-here")
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The result of the GraphQL query or mutation.

#### Response Example (List VMs)
```json
{
  "data": {
    "vms": {
      "domains": [
        {
          "id": "vm-uuid-here",
          "name": "MyVM",
          "state": "running"
        }
      ]
    }
  }
}
```
```

--------------------------------

### Initiate Flash Backup

Source: https://context7.com/unraid/api/llms.txt

Start a flash drive backup to a specified remote location with optional configurations like dry run.

```graphql
mutation InitiateFlashBackup {
  initiateFlashBackup(input: {
    remoteName: "my-gdrive"
    sourcePath: "/boot"
    destinationPath: "/unraid-backup"
    options: { "--dry-run": false }
  }) {
    status
    jobId
  }
}
```

--------------------------------

### Validate Plugin Environment Setup

Source: https://github.com/unraid/api/blob/main/plugin/README.md

Checks if the current environment setup is valid for plugin development. Run this command after initializing the environment to ensure everything is configured correctly.

```bash
pnpm run env:validate
```

--------------------------------

### Migration Script Example

Source: https://github.com/unraid/api/blob/main/api/src/unraid-api/graph/README.md

A script to assist in identifying resolvers that require migration.

```typescript
migration-script.ts: A script to help identify which resolvers need to be migrated
```

--------------------------------

### Run API Server

Source: https://github.com/unraid/api/blob/main/AGENTS.md

Starts the NestJS API server locally. Access it at http://localhost:3001.

```bash
cd api && pnpm dev
```

--------------------------------

### Build and Run Docker Container for Plugin Development

Source: https://github.com/unraid/api/blob/main/plugin/README.md

Builds the Docker container and starts it, automatically building dependencies. This is the initial step for local plugin development.

```bash
pnpm run docker:build-and-run
```

--------------------------------

### Enable Next-Generation Docker Features

Source: https://github.com/unraid/api/blob/main/api/docs/developer/docker.md

Start the Unraid API with next-generation Docker features enabled for local testing. This can be done by setting an environment variable.

```bash
ENABLE_NEXT_DOCKER_RELEASE=true unraid-api start
```

--------------------------------

### Enable Modal Testing Tool

Source: https://github.com/unraid/api/blob/main/AGENTS.md

Starts the developer tools with the modal testing tool enabled.

```bash
unraid-api developer --enable-modal
```

--------------------------------

### View Debug Logs

Source: https://github.com/unraid/api/blob/main/api/docs/developer/development.md

Start the API with debug logging enabled and then use the 'unraid-api logs' command to trail the logs.

```bash
LOG_LEVEL=debug unraid-api start
```

```bash
unraid-api logs
```

--------------------------------

### Run Unraid Plugin Builder Docker Container

Source: https://github.com/unraid/api/blob/main/plugin/README.md

Starts the Docker container for the Unraid Plugin Builder. This command is used to run the builder in a Dockerized environment.

```bash
pnpm docker:run
```

--------------------------------

### Configure Log Level

Source: https://github.com/unraid/api/blob/main/api/docs/developer/development.md

Set the desired log level when starting the API. Available levels include all, trace, debug, info, warn, error, fatal, mark, and off.

```bash
LOG_LEVEL=debug unraid-api start --debug
```

--------------------------------

### Get Full System Information

Source: https://context7.com/unraid/api/llms.txt

Query comprehensive system details including time, machine ID, CPU specifications, memory layout, OS information, system hardware, baseboard details, version information for core components and packages, and network interface configurations.

```graphql
query GetSystemInfo {
  info {
    time
    machineId
    cpu {
      manufacturer
      brand
      cores
      threads
      speed
      speedmax
      topology
      packages { totalPower temp }
    }
    memory {
      layout { size bank type clockSpeed manufacturer }
    }
    os {
      platform
      distro
      release
      kernel
      hostname
      uptime
    }
    system {
      manufacturer
      model
      serial
    }
    baseboard {
      manufacturer
      model
      memMax
      memSlots
    }
    versions {
      core { unraid api kernel }
      packages { docker node php nginx }
    }
    networkInterfaces {
      name
      ipAddress
      macAddress
      status
      gateway
    }
  }
}
```

--------------------------------

### Get System Variables

Source: https://context7.com/unraid/api/llms.txt

Retrieve various system configuration variables, including version, name, timezone, SSL/SSH port settings, array start status, share counts, registration status, and registration details.

```graphql
query GetVars {
  vars {
    version
    name
    timeZone
    comment
    useSsl
    port
    portssl
    useSsh
    portssh
    startArray
    shareCount
    shareSmbCount
    regState
    regTo
  }
}
```

--------------------------------

### Web Summary-Step Init And Apply Flow

Source: https://github.com/unraid/api/blob/main/web/src/components/Onboarding/UPGRADE_ONBOARDING.md

Details the readiness/initialization and apply sequences for the Unraid web summary step.

```APIDOC
## Web Summary-Step Init And Apply Flow

### Readiness/Initialization

On mount, the summary step initiates the following queries:

1. `GetCoreSettings` (baseline).
2. `InstalledUnraidPlugins`.
3. `GetAvailableLanguages`.
4. A 10s readiness timer; if the baseline is still unavailable, the apply process can continue in a best-effort mode.

### Apply Sequence (When User Clicks Confirm)

1. Compute baseline vs. target settings.
2. Apply core settings (timezone, identity, theme).
3. Apply locale (installing language if needed).
4. Install selected plugins not already installed.
5. Apply SSH settings (with optimistic verification).
6. Display the final result dialog based on apply/result precedence.
7. Advance to Next Steps after user confirmation.

### Endpoint/Operation Mapping

| Purpose | Operation |
| --- | --- |
| Baseline settings | `GetCoreSettings` |
| Installed plugin names | `InstalledUnraidPlugins` |
| Language metadata | `GetAvailableLanguages` |
| Update timezone | `UpdateSystemTime` |
| Update identity | `UpdateServerIdentity` |
| Update theme | `setTheme` |
| Update locale | `SetLocale` |
| Update SSH | `UpdateSshSettings` |
| Install plugin | `InstallPlugin` (+ operation tracking query/subscription) |
| Install language pack | `InstallLanguage` (+ operation tracking query/subscription) |
| Final onboarding completion | `CompleteOnboarding` (triggered from Next Steps) |

#### GetCoreSettings

- **Method**: GET
- **Endpoint**: `/api/core/settings`
- **Description**: Retrieves the core system settings.
- **Response**: Returns baseline settings.

#### InstalledUnraidPlugins

- **Method**: GET
- **Endpoint**: `/api/plugins/installed`
- **Description**: Retrieves a list of installed Unraid plugins.
- **Response**: Returns a list of installed plugin names.

#### GetAvailableLanguages

- **Method**: GET
- **Endpoint**: `/api/languages/available`
- **Description**: Retrieves metadata for available languages.
- **Response**: Returns language metadata.

#### UpdateSystemTime

- **Method**: POST
- **Endpoint**: `/api/system/time`
- **Description**: Updates the system timezone.
- **Request Body**: 
  - **timezone** (string) - Required - The new timezone to set.
- **Response**: Success message.

#### UpdateServerIdentity

- **Method**: POST
- **Endpoint**: `/api/server/identity`
- **Description**: Updates the server identity settings.
- **Request Body**: 
  - **identity** (object) - Required - The new identity settings.
- **Response**: Success message.

#### setTheme

- **Method**: POST
- **Endpoint**: `/api/settings/theme`
- **Description**: Sets the system theme.
- **Request Body**: 
  - **theme** (string) - Required - The theme to apply.
- **Response**: Success message.

#### SetLocale

- **Method**: POST
- **Endpoint**: `/api/locale`
- **Description**: Sets the system locale.
- **Request Body**: 
  - **locale** (string) - Required - The locale to set.
- **Response**: Success message.

#### UpdateSshSettings

- **Method**: POST
- **Endpoint**: `/api/ssh/settings`
- **Description**: Updates SSH settings.
- **Request Body**: 
  - **settings** (object) - Required - The SSH settings to apply.
- **Response**: Success message.

#### InstallPlugin

- **Method**: POST
- **Endpoint**: `/api/plugins/install`
- **Description**: Installs a specified plugin.
- **Request Body**: 
  - **plugin_name** (string) - Required - The name of the plugin to install.
- **Response**: Operation tracking information.

#### InstallLanguage

- **Method**: POST
- **Endpoint**: `/api/languages/install`
- **Description**: Installs a specified language pack.
- **Request Body**: 
  - **language_code** (string) - Required - The code of the language pack to install.
- **Response**: Operation tracking information.

#### CompleteOnboarding

- **Method**: POST
- **Endpoint**: `/api/onboarding/complete`
- **Description**: Marks the onboarding process as complete.
- **Response**: Success message.
```

--------------------------------

### Update Settings

Source: https://context7.com/unraid/api/llms.txt

Modify system settings by providing a JSON input object. The example shows updating the server name. The response indicates if a restart is required and returns updated values and any warnings.

```graphql
mutation UpdateSettings {
  updateSettings(input: {
    "server": { "name": "MyUnraidServer" }
  }) {
    restartRequired
    values
    warnings
  }
}
```

--------------------------------

### Build Web Package

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Navigate to the web directory and run this command to build the web components package.

```bash
cd web
pnpm build
```

--------------------------------

### Build for Production

Source: https://github.com/unraid/api/blob/main/unraid-ui/README.md

Build the Unraid UI library for production deployment.

```bash
npm run build
```

--------------------------------

### Run Onboarding Summary Step Tests

Source: https://github.com/unraid/api/blob/main/web/src/components/Onboarding/UPGRADE_ONBOARDING.md

Execute the targeted test suite for the OnboardingSummaryStep component using pnpm.

```bash
pnpm --filter @unraid/web exec vitest run __test__/components/Onboarding/OnboardingSummaryStep.test.ts
```

--------------------------------

### Deploy All Components to Development Server

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Builds and deploys all components to the specified Unraid server IP.

```bash
pnpm unraid:deploy <SERVER_IP>
```

--------------------------------

### GraphQL Mutation to Start or Stop the Array

Source: https://context7.com/unraid/api/llms.txt

Use this mutation to change the desired state of the Unraid array, such as starting or stopping it.

```graphql
# Start or stop the array
mutation SetArrayState {
  array {
    setState(input: { desiredState: START }) {
      state
    }
  }
}
```

--------------------------------

### Deploy Web Package to Development Server

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Navigate to the web directory and deploy the web components package to the specified Unraid server IP.

```bash
cd web
pnpm unraid:deploy <SERVER_IP>
```

--------------------------------

### Disable GraphQL Sandbox

Source: https://github.com/unraid/api/blob/main/AGENTS.md

Starts the developer tools with the GraphQL sandbox disabled.

```bash
unraid-api developer --sandbox false
```

--------------------------------

### Run Onboarding Core Settings Step Tests

Source: https://github.com/unraid/api/blob/main/web/src/components/Onboarding/UPGRADE_ONBOARDING.md

Execute the targeted test suite for the OnboardingCoreSettingsStep component using pnpm.

```bash
pnpm --filter @unraid/web exec vitest run __test__/components/Onboarding/OnboardingCoreSettingsStep.test.ts
```

--------------------------------

### Build API Package

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Navigate to the API directory and run this command to build the API package.

```bash
cd api
pnpm build
```

--------------------------------

### Disable Modal Testing Tool

Source: https://github.com/unraid/api/blob/main/AGENTS.md

Starts the developer tools with the modal testing tool disabled.

```bash
unraid-api developer --disable-modal
```

--------------------------------

### DockerAutostartService

Source: https://github.com/unraid/api/blob/main/api/docs/developer/docker.md

Manages container auto-start configuration, including parsing auto-start files, maintaining order, and persisting changes.

```APIDOC
## DockerAutostartService

### Description
Manages container auto-start configuration.

### Features
- Parses auto-start file format (name + wait time per line)
- Maintains auto-start order and wait times
- Persists configuration changes
- Tracks container primary names
```

--------------------------------

### Build Development Version of Web Package

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Navigate to the web directory and run this command to build a development version of the web components package.

```bash
cd web
pnpm build:dev
```

--------------------------------

### Setup Remote Access

Source: https://context7.com/unraid/api/llms.txt

Configure remote access settings for Unraid Connect, specifying access and forward types.

```graphql
mutation SetupRemoteAccess {
  setupRemoteAccess(input: {
    accessType: DYNAMIC
    forwardType: UPNP
  })
}
```

--------------------------------

### Get RClone Configuration

Source: https://context7.com/unraid/api/llms.txt

Retrieve RClone configuration details, including drives, remotes, and the configuration form schema.

```graphql
query GetRCloneConfig {
  rclone {
    drives { name options }
    remotes { name type parameters config }
    configForm(formOptions: { providerType: "drive", showAdvanced: false }) {
      id
      dataSchema
      uiSchema
    }
  }
}
```

--------------------------------

### Adding New Onboarding Steps

Source: https://github.com/unraid/api/blob/main/web/src/components/Onboarding/UPGRADE_ONBOARDING.md

Instructions for developers on how to add new steps to the Unraid onboarding flow, including component creation, registration, and flow integration.

```APIDOC
## Adding New Onboarding Steps

### Description
This guide outlines the process for adding new custom steps to the Unraid onboarding modal.

### Steps

1.  **Create the Step Component**: Develop a Vue component for the new step located in `web/src/components/Onboarding/steps/`. Ensure it adheres to the `Props` contract:
    ```typescript
    export interface Props {
      onComplete: () => void;
      onBack?: () => void;
      showBack?: boolean;
      onSkip?: () => void;
      showSkip?: boolean;
      isSavingStep?: boolean;
    }
    ```

2.  **Register Component and Metadata**: Add the new component to `stepComponents` and its metadata (title, description, icon) to `stepMetadata` in `web/src/components/Onboarding/stepRegistry.ts`.

3.  **Update Step ID Unions**: Include the new step's ID in the `StepId` union types defined in `web/src/components/Onboarding/OnboardingModal.vue` and `web/src/components/Onboarding/OnboardingSteps.vue`.

4.  **Add to Client-Side Flow**: Integrate the step into the `HARDCODED_STEPS` array in `web/src/components/Onboarding/OnboardingModal.vue`. Configure its `required` flag and update `availableSteps` / `filteredSteps` logic if it's conditional.

5.  **Wire Per-Step Props**: Implement a `switch` case within `currentStepProps` in `OnboardingModal.vue` to pass the correct callbacks and flags (e.g., `onComplete`, `onBack`) to the new step component.

6.  **Add/Update Tests**: Ensure comprehensive testing by updating `web/__test__/components/Onboarding/OnboardingModal.test.ts` and creating step-specific test files as needed.
```

--------------------------------

### GraphQL Mutation to Start a Parity Check

Source: https://context7.com/unraid/api/llms.txt

Initiate a parity check on the Unraid array, with an option to enable correction of errors.

```graphql
# Start a parity check with correction
mutation StartParityCheck {
  parityCheck {
    start(correct: true)
  }
}
```

--------------------------------

### Deploy API Package to Development Server

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Navigate to the API directory and deploy the API package to the specified Unraid server IP.

```bash
cd api
pnpm unraid:deploy <SERVER_IP>
```

--------------------------------

### Run Onboarding Service Tests

Source: https://github.com/unraid/api/blob/main/web/src/components/Onboarding/UPGRADE_ONBOARDING.md

Execute the targeted test suite for the onboarding service within the Unraid API using pnpm.

```bash
pnpm --filter @unraid/api exec vitest run src/unraid-api/graph/resolvers/customization/onboarding.service.spec.ts
```

--------------------------------

### Deploy Plugin Package to Development Server

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Navigate to the plugin directory and deploy the plugin package to the specified Unraid server IP.

```bash
cd plugin
pnpm unraid:deploy <SERVER_IP>
```

--------------------------------

### Docker Container Management

Source: https://context7.com/unraid/api/llms.txt

Full Docker container lifecycle management including start, stop, pause, update, and log retrieval.

```APIDOC
## Docker Container Management

### Description
Full Docker container lifecycle management including start, stop, pause, update, and log retrieval.

### Method
POST

### Endpoint
`/graphql`

### Parameters
#### Request Body
- **query** (string) - Required - The GraphQL query string.
- **mutation** (string) - Required - The GraphQL mutation string.

### Request Example (List Containers)
```graphql
query GetDockerContainers {
  docker {
    containers {
      id
      names
      image
      state
      status
      autoStart
      ports { privatePort publicPort type }
      isUpdateAvailable
      webUiUrl
      iconUrl
    }
    networks { id name driver }
    portConflicts {
      containerPorts { privatePort type containers { id name } }
    }
  }
}
```

### Request Example (Start Container)
```graphql
mutation StartContainer {
  docker {
    start(id: "server123:abc123def456") {
      id
      state
      status
    }
  }
}
```

### Request Example (Stop Container)
```graphql
mutation StopContainer {
  docker {
    stop(id: "server123:abc123def456") {
      id
      state
      status
    }
  }
}
```

### Request Example (Update Container)
```graphql
mutation UpdateContainer {
  docker {
    updateContainer(id: "server123:abc123def456") {
      id
      image
      isUpdateAvailable
    }
  }
}
```

### Request Example (Get Container Logs)
```graphql
query GetContainerLogs {
  docker {
    logs(id: "server123:abc123def456", tail: 100) {
      containerId
      lines { timestamp message }
      cursor
    }
  }
}
```

### Request Example (Subscribe to Container Stats)
```graphql
subscription DockerStats {
  dockerContainerStats {
    id
    cpuPercent
    memUsage
    memPercent
    netIO
    blockIO
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - The result of the GraphQL query, mutation, or subscription.

#### Response Example (List Containers)
```json
{
  "data": {
    "docker": {
      "containers": [
        {
          "id": "container123",
          "names": "/my-container",
          "image": "nginx:latest",
          "state": "running",
          "status": "running",
          "autoStart": true,
          "ports": [{"privatePort": 80, "publicPort": 8080, "type": "tcp"}],
          "isUpdateAvailable": false,
          "webUiUrl": "http://localhost:8080",
          "iconUrl": "/icons/nginx.png"
        }
      ],
      "networks": [{"id": "net1", "name": "bridge", "driver": "bridge"}],
      "portConflicts": []
    }
  }
}
```
```

--------------------------------

### GraphQL Query: Get Temperature Metrics

Source: https://github.com/unraid/api/blob/main/api/docs/developer/temperature.md

Query the `metrics` endpoint to retrieve a snapshot of current temperature metrics from all configured sensors.

```APIDOC
## Query: `metrics` -> `temperature`

Returns a snapshot of the current temperature metrics.

### Request Example

```graphql
query {
  metrics {
    temperature {
      id
      summary {
        average
        hottest {
          name
          current {
            value
            unit
          }
        }
      }
      sensors {
        id
        name
        type
        current {
          value
          unit
          status
        }
        history {
          value
          timestamp
        }
      }
    }
  }
}
```

### Response Example (Success - 200)

```json
{
  "data": {
    "metrics": {
      "temperature": {
        "id": "temperature",
        "summary": {
          "average": 45.5,
          "hottest": {
            "name": "CPU Core 1",
            "current": {
              "value": 65.0,
              "unit": "celsius"
            }
          }
        },
        "sensors": [
          {
            "id": "cpu_0",
            "name": "CPU Core 1",
            "type": "cpu",
            "current": {
              "value": 65.0,
              "unit": "celsius",
              "status": "normal"
            },
            "history": [
              {
                "value": 64.5,
                "timestamp": 1678886400
              },
              {
                "value": 65.0,
                "timestamp": 1678886460
              }
            ]
          },
          {
            "id": "disk_1",
            "name": "sda",
            "type": "disk",
            "current": {
              "value": 35.0,
              "unit": "celsius",
              "status": "normal"
            },
            "history": [
              {
                "value": 34.8,
                "timestamp": 1678886400
              },
              {
                "value": 35.0,
                "timestamp": 1678886460
              }
            ]
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### Build All Packages

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Execute this command from the root of the monorepo to build all packages.

```bash
pnpm build
```

--------------------------------

### Unraid API Key Management Help

Source: https://github.com/unraid/api/blob/main/api/README.md

Shows the available options for managing Unraid API keys. This command is essential for setting up authentication for the local API.

```sh
unraid-api key --help
```

--------------------------------

### GraphQL Playground Request Headers

Source: https://github.com/unraid/api/blob/main/api/docs/developer/development.md

Example of the HTTP headers required to authenticate with the GraphQL playground. Replace '__REPLACE_ME_WITH_API_KEY__' with your actual API key.

```json
{
    "x-api-key": "__REPLACE_ME_WITH_API_KEY__"
}
```

--------------------------------

### Nix Development Environment

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

If using Nix, run this command from the repository root before setting up the monorepo to enter the development environment.

```bash
nix develop
```

--------------------------------

### Get Unraid Connect Status

Source: https://context7.com/unraid/api/llms.txt

Query the status of Unraid Connect, including dynamic remote access, settings, and cloud integration details.

```graphql
query GetConnectStatus {
  connect {
    dynamicRemoteAccess {
      enabledType
      runningType
      error
    }
    settings {
      values {
        accessType
        forwardType
        port
      }
    }
  }
  cloud {
    apiKey { valid error }
    minigraphql { status timeout error }
    cloud { status ip error }
  }
  remoteAccess {
    accessType
    forwardType
    port
  }
}
```

--------------------------------

### Get and Update System Time

Source: https://context7.com/unraid/api/llms.txt

Query current system time details and update time settings, including timezone and NTP configuration.

```graphql
query GetSystemTime {
  systemTime {
    currentTime
    timeZone
    useNtp
    ntpServers
  }
  timeZoneOptions { value label }
}
```

```graphql
mutation UpdateSystemTime {
  updateSystemTime(input: {
    timeZone: "America/Los_Angeles"
    useNtp: true
    ntpServers: ["pool.ntp.org", "time.google.com", "", ""]
  }) {
    timeZone
    useNtp
  }
}
```

--------------------------------

### GraphQL Query to Get Container Logs

Source: https://context7.com/unraid/api/llms.txt

Retrieve the logs for a specific Docker container, with an option to specify the number of lines to fetch from the end.

```graphql
# Get container logs
query GetContainerLogs {
  docker {
    logs(id: "server123:abc123def456", tail: 100) {
      containerId
      lines { timestamp message }
      cursor
    }
  }
}
```

--------------------------------

### Initialize Plugin Environment

Source: https://github.com/unraid/api/blob/main/plugin/README.md

Creates the initial .env file required for the plugin development environment. Run this command once to set up your environment variables.

```bash
pnpm run env:init
```

--------------------------------

### Deploy Project to Unraid

Source: https://github.com/unraid/api/blob/main/readme.md

Deploy the entire project to your Unraid server. Replace SERVER_IP with your Unraid server's IP address.

```bash
pnpm unraid:deploy SERVER_IP
```

--------------------------------

### Create New Release

Source: https://github.com/unraid/api/blob/main/api/docs/developer/development.md

Run this command to create a new version. After it returns commands, execute ONLY the 'git push' section.

```bash
npm run release
```

--------------------------------

### GraphQL Subscription for Container Statistics

Source: https://github.com/unraid/api/blob/main/api/docs/developer/docker.md

Subscribe to this stream for real-time Docker container statistics. The stream starts automatically on the first subscription and stops when all clients disconnect.

```graphql
type Subscription {
  dockerContainerStats: DockerContainerStats!
}
```

--------------------------------

### Create New Prerelease

Source: https://github.com/unraid/api/blob/main/api/docs/developer/development.md

Use this command to create a prerelease, specifying the tag (e.g., 'alpha').

```bash
npm run release -- --prerelease alpha
```

--------------------------------

### Display Unraid API CLI Help

Source: https://github.com/unraid/api/blob/main/api/docs/developer/workflows.md

Command to display help information for the Unraid API CLI when working with a deployed API.

```bash
unraid-api --help
```

--------------------------------

### Clean Plugin Environment Variables

Source: https://github.com/unraid/api/blob/main/plugin/README.md

Removes the .env file, effectively resetting the environment variables for the plugin builder. Use this command to revert environment setup.

```bash
pnpm env:clean
```