### Frontend Development Setup

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/CONTRIBUTING.md

Navigates to the frontend directory, installs dependencies, and starts the development server.

```bash
cd frontend
npm ci
npm run dev
```

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

### Manual Frontend Setup

Source: https://github.com/hitheshkaranth/openterminalui/wiki/Getting-Started

Instructions for setting up the frontend manually, including installing dependencies and starting the development server.

```bash
cd frontend

# Install dependencies
npm ci

# Start dev server
npm run dev
```

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

### Backend Development Setup

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/CONTRIBUTING.md

Sets up the Python virtual environment, installs dependencies, copies the environment file, and starts the development server.

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\\Scripts\\activate
pip install -r backend/requirements.txt
pip install -r backend/requirements-dev.txt
cp .env.example .env
PYTHONPATH=. uvicorn backend.main:app --reload --port 8000
```

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

### Set Up Frontend Development Environment

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/wiki/Contributing.md

Navigate to the frontend directory, install dependencies, and start the development server for hot-reloading.

```bash
cd frontend
npm ci
npm run dev     # hot-reload dev server on :5173
```

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

### Set Up Backend Development Environment

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/wiki/Contributing.md

Create a virtual environment, activate it, and install backend dependencies. Copy the example environment file for local configuration.

```bash
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r backend/requirements.txt
pip install -r backend/requirements-dev.txt   # test dependencies
cp .env.example .env        # fill in keys as needed for local testing
```

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

### Manual Docker Compose Setup

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/README.md

Manually set up the application using Docker Compose. Copy the example .env file, add API keys if available, and then start the services.

```bash
cp .env.example .env      # add API keys if you have them
docker compose up --build            # Backend + Frontend + Redis (SQLite)
docker compose --profile postgres up --build   # with PostgreSQL
```

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

### Local Development Frontend Setup

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/README.md

Set up the frontend for local development. Navigate to the frontend directory, install Node.js dependencies, and run the development server.

```bash
# Frontend (separate terminal)
cd frontend && npm ci && npm run dev
```

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

### Manual Backend Setup

Source: https://github.com/hitheshkaranth/openterminalui/wiki/Getting-Started

Steps to set up the backend manually, including creating a virtual environment, installing dependencies, configuring environment variables, and running the development server.

```bash
cd OpenTerminalUI

# Create virtual environment
python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r backend/requirements.txt

# Configure environment
cp .env.example .env         # edit with your keys

# Run the backend
PYTHONPATH=. uvicorn backend.main:app --reload --port 8000
```

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

### Local Development Backend Setup

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/README.md

Set up the backend for local development. This involves creating a virtual environment, installing dependencies, and running the Uvicorn server with hot reload.

```bash
# Backend
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r backend/requirements.txt
PYTHONPATH=. uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000
```

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

### Force Installation Mode

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/README.md

Optionally, force the installer to use Docker or a local setup by setting the OTUI_MODE environment variable.

```bash
OTUI_MODE=docker ./install.sh          # Force Docker mode
OTUI_MODE=local ./install.sh          # Force local mode
```

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

### Clone and Start with Docker Compose

Source: https://github.com/hitheshkaranth/openterminalui/wiki/Getting-Started

Use this command to clone the repository, configure environment variables, and start the application using Docker Compose.

```bash
git clone https://github.com/YOUR_ORG/OpenTerminalUI.git
cd OpenTerminalUI

cp .env.example .env
# Edit .env and fill in your API keys (see table below)

docker compose up --build
```

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

### Quick Start with Docker

Source: https://github.com/hitheshkaranth/openterminalui/wiki/Home

Use these commands to quickly set up and run OpenTerminalUI using Docker. Ensure you fill in your API keys in the .env file before starting.

```bash
cp .env.example .env          # fill in API keys
docker compose up --build     # starts backend + frontend
```

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

### Start Docker Services with Build

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/PHASE2_QC_GUIDELINES.md

Starts Docker services in detached mode, rebuilding images if necessary.

```bash
docker compose up -d --build
```

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

### Start Docker Compose with PostgreSQL and Redis

Source: https://github.com/hitheshkaranth/openterminalui/wiki/Getting-Started

This command enables PostgreSQL and Redis profiles when starting the application with Docker Compose.

```bash
docker compose --profile postgres --profile redis up --build
```

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

### Set up Backend Locally

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/wiki/Getting-Started.md

Commands to set up a Python virtual environment, install dependencies, and run the backend development server locally.

```bash
python -m venv .venv
.\.venv\Scripts\activate
pip install -r backend/requirements.txt
$env:PYTHONPATH='.'
uvicorn backend.main:app --reload --port 8000
```

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

### Start OpenTerminalUI (macOS/Linux)

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/INSTALLATION.md

Execute the shell script to start OpenTerminalUI on macOS or Linux.

```bash
sh ./scripts/docker-up.sh
```

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

### Run Backend Development Server

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/wiki/Contributing.md

Start the backend development server with hot-reloading enabled.

```bash
PYTHONPATH=. uvicorn backend.main:app --reload --port 8000
```

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

### Install uuid Package

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/plans/2026-02-24-chart-workstation.md

Install the 'uuid' package and its TypeScript types if they are missing from the frontend project.

```bash
cd frontend && npm install uuid @types/uuid
```

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

### Run Backend and Frontend Tests

Source: https://github.com/hitheshkaranth/openterminalui/wiki/Getting-Started

Commands to execute the test suite for both the backend and frontend to verify the installation.

```bash
make gate
# or individually:
PYTHONPATH=. pytest backend/tests -q --cov=backend --cov-fail-under=45
cd frontend && npm test
```

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

### Install uuid for Frontend Project

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/plans/2026-02-24-chart-workstation.md

Installs the 'uuid' package and its types for frontend development. This is required for generating unique IDs for chart slots.

```bash
cd frontend && npm install uuid && npm install --save-dev @types/uuid
```

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

### Install Playwright Browsers

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/plans/2026-02-21-public-commit-prep.md

Installs the necessary Playwright browser binaries, specifically Chromium, for end-to-end testing. This is a prerequisite if browsers are not already installed.

```bash
npx playwright install --with-deps chromium 2>&1 | tail -5
```

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

### Display Login Credentials

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/README.md

After the installer finishes, it prints the URL, email, and a generated unique password for the first login. These are also saved in the .env file.

```text
 OpenTerminalUI is ready  ->  http://localhost:8000
   email:    admin@openterminal.local
   password: <generated unique password>
```

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

### Clone Repository and Run Installer

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/README.md

Clone the OpenTerminalUI repository and execute the installation script. The script auto-detects the OS and environment (Docker or local Python/Node) and configures the application.

```bash
git clone https://github.com/Hitheshkaranth/OpenTerminalUI.git
cd OpenTerminalUI
./install.sh          # macOS / Linux / WSL   (Windows: ./install.ps1)
```

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

### Start OpenTerminalUI with Redis and PostgreSQL (macOS/Linux)

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/INSTALLATION.md

Start OpenTerminalUI with both Redis and PostgreSQL enabled using a shell script. This command specifies both profiles.

```bash
sh ./scripts/docker-up.sh --redis --postgres
```

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

### Install Playwright and Run E2E Tests

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/plans/2026-02-21-public-commit-prep-design.md

Installs the Chromium browser for Playwright and runs the end-to-end test suite. This command should be run from the project root, specifying the frontend directory.

```shell
npx playwright install --with-deps chromium && npm run test:e2e --prefix frontend
```

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

### Docker Compose with PostgreSQL Profile

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/DATABASE_MIGRATION.md

Start Docker containers using the PostgreSQL profile for development or testing. This command builds the images and starts the services in detached mode.

```bash
docker compose --profile postgres up -d --build
```

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

### Clone, Build, and Launch OpenTerminalUI with Docker Compose

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/site/index.html

Quickly deploy the full OpenTerminalUI stack using Docker Compose. Ensure you have Docker installed.

```bash
git clone https://github.com/  
  Hitheshkaranth/OpenTerminalUI.git  
$ cd OpenTerminalUI  
$ docker compose up --build
```

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

### Run Interactive Key Setup

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/README.md

Execute the 'make keys' command or the setup-keys.sh script to launch an interactive wizard for adding or updating API keys in the .env file.

```bash
make keys          # or: ./scripts/setup-keys.sh
```

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

### Build Frontend Application

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/README.md

Navigates to the frontend directory and runs the build command using npm.

```bash
cd frontend
npm run build
```

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

### API Smoke Test: GET Alerts

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/PHASE2_QC_GUIDELINES.md

Sends a GET request to the /api/alerts endpoint to test its functionality.

```bash
GET /api/alerts
```

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

### Start OpenTerminalUI with Redis (macOS/Linux)

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/INSTALLATION.md

Start OpenTerminalUI with Redis enabled using a shell script. This command specifies the Redis profile.

```bash
sh ./scripts/docker-up.sh --redis
```

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

### Run E2E Tests with Backend Running

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/plans/2026-02-21-public-commit-prep.md

Starts the backend server using uvicorn and then runs the frontend end-to-end tests. This is necessary if the E2E tests require a live backend environment.

```bash
PYTHONPATH=. uvicorn backend.main:app --host 127.0.0.1 --port 8010 &
sleep 5
npm run test:e2e --prefix frontend
```

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

### Start OpenTerminalUI (Windows PowerShell)

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/INSTALLATION.md

Execute the PowerShell script to start OpenTerminalUI on Windows. Ensure the execution policy is bypassed for script execution.

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\docker-up.ps1
```

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

### Run Core Expansion and Adapter Registry Tests

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/PHASE2_QC_GUIDELINES.md

Executes specific backend tests for Phase 2 core expansion and adapter registry functionality.

```bash
pytest -q backend/tests/test_phase2_core_expansion.py backend/tests/test_adapter_registry_phase2.py
```

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

### Run Frontend Unit Tests

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/CONTRIBUTING.md

Navigates to the frontend directory and runs the unit tests using npm.

```bash
cd frontend && npm test
```

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

### Build from Source for Local Development

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/site/index.html

Set up a local development environment by building OpenTerminalUI from source. This enables hot-reloading for both backend and frontend.

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
PYTHONPATH=. uvicorn backend.main:app --reload
```

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

### Start OpenTerminalUI on a different port (macOS/Linux)

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/INSTALLATION.md

Start OpenTerminalUI on a custom port (e.g., 8010) using a shell script. This command specifies the desired port.

```bash
sh ./scripts/docker-up.sh --port 8010
```

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

### Start OpenTerminalUI with Redis (Windows PowerShell)

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/INSTALLATION.md

Start OpenTerminalUI with Redis enabled using PowerShell. This command bypasses the execution policy and specifies the Redis profile.

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\docker-up.ps1 -Redis
```

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

### Document Environment Variables

Source: https://github.com/hitheshkaranth/openterminalui/wiki/Contributing

Any new environment variables introduced must be documented in the '.env.example' file. This ensures proper configuration management.

```dotenv
.env.example
```

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

### Chart Workstation E2E Test Setup

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/plans/2026-02-24-chart-workstation.md

End-to-end test suite for the Chart Workstation feature using Playwright. Includes authentication setup and API mocking.

```typescript
import { expect, test } from "@playwright/test";

function makeJwt(payload: Record<string, unknown>): string {
  const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
  return `x.${encoded}.y`;
}

const accessToken = makeJwt({
  sub: "e2e-user",
  email: "e2e@example.com",
  role: "trader",
  exp: Math.floor(Date.now() / 1000) + 3600,
});
const refreshToken = makeJwt({ exp: Math.floor(Date.now() / 1000) + 7200 });

function setupAuth(page: import("@playwright/test").Page) {
  return page.addInitScript(
    ([at, rt]) => {
      localStorage.setItem("ot-access-token", at);
      localStorage.setItem("ot-refresh-token", rt);
    },
    [accessToken, refreshToken],
  );
}

test.describe("chart workstation", () => {
  test.beforeEach(async ({ page }) => {
    // Mock chart API
    await page.route("**/api/v3/chart**", async (route) => {
      await route.fulfill({
        json: {
          ticker: "RELIANCE",
          interval: "1d",
          currency: "INR",
          data: Array.from({ length: 10 }, (_, i) => ({
            t: Math.floor(Date.now() / 1000) - (10 - i) * 86400,
            o: 2500 + i * 10,
            h: 2520 + i * 10,
            l: 2480 + i * 10,
            c: 2510 + i * 10,
            v: 1000000,
          })),
        },
      });
    });

    // Mock search API
    await page.route("**/api/search**", async (route) => {
      await route.fulfill({
        json: {
          results: [
            { ticker: "RELIANCE", name: "Reliance Industries", exchange: "NSE", country_code: "IN" },
            { ticker: "INFY", name: "Infosys Ltd", exchange: "NSE", country_code: "IN" },
          ],
        },
      });
    });

    // Mock batch chart API
    await page.route("**/api/charts/batch", async (route) => {
      await route.fulfill({ json: {} });
    });

    await setupAuth(page);
    await page.goto("/equity/chart-workstation");
  });

  test("page loads with chart workstation heading", async ({ page }) => {
    await expect(page.getByText("Chart Workstation")).toBeVisible();
    await expect(page.getByTestId("chart-workstation")).toBeVisible();
  });

  test("shows add chart button and placeholder", async ({ page }) => {
    await expect(page.getByTestId("add-chart-btn")).toBeVisible();
    await expect(page.getByTestId("add-chart-placeholder")).toBeVisible();
  });

  test("can add a second chart panel", async ({ page }) => {
    await page.getByTestId("add-chart-btn").click();
    const panels = page.getByTestId(/chart-panel-/);
    await expect(panels).toHaveCount(2);
  });

  test("layout selector buttons are visible", async ({ page }) => {
    // Layout selector renders grid buttons (1×1, 2×1, 2×2, 3×1, 3×2)
    const layoutBtns = page.locator(".layout-btn");
    await expect(layoutBtns).toHaveCount(5);
  });

  test("remove chart button reduces panel count", async ({ page }) => {
    // Add a second chart first
    await page.getByTestId("add-chart-btn").click();
    await expect(page.getByTestId(/chart-panel-/)).toHaveCount(2);

    // Remove the first panel
    const removeBtn = page.locator("[data-testid^='remove-chart-']").first();
    await removeBtn.scrollIntoViewIfNeeded();
    await removeBtn.click();
    await expect(page.getByTestId(/chart-panel-/)).toHaveCount(1);
  });

  test("sidebar shows Charts nav item", async ({ page }) => {
    // The equity layout sidebar should have a Charts link
    await expect(page.getByRole("link", { name: "Charts" })).toBeVisible();
  });
});

```

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

### Run Frontend Unit Tests

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/README.md

Navigates to the frontend directory and runs unit tests using vitest.

```bash
npx vitest run
```

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

### Build Frontend

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/PHASE2_QC_GUIDELINES.md

Builds the frontend application using npm. Ensure to run this command from the project root, specifying the frontend directory.

```bash
npm.cmd run build --prefix frontend
```

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

### Start OpenTerminalUI with Redis and PostgreSQL (Windows PowerShell)

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/INSTALLATION.md

Start OpenTerminalUI with both Redis and PostgreSQL enabled using PowerShell. This command bypasses the execution policy and specifies both profiles.

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\docker-up.ps1 -Redis -Postgres
```

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

### Run Backend Regression Tests

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/paper_trading_regression_checklist.md

Navigate to the backend directory, activate the virtual environment, compile Python files, and run pytest to verify regression.

```bash
cd backend && source .venv/bin/activate && python -m compileall . && pytest -q
```

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

### Run Frontend End-to-End Tests

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/CONTRIBUTING.md

Navigates to the frontend directory and runs the end-to-end tests using npm.

```bash
cd frontend && npm run test:e2e
```

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

### Start OpenTerminalUI on a different port (Windows PowerShell)

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/INSTALLATION.md

Start OpenTerminalUI on a custom port (e.g., 8010) using PowerShell. This command bypasses the execution policy and specifies the desired port.

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\docker-up.ps1 -Port 8010
```

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

### Frontend Build and Test

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/superpowers/specs/2026-03-19-bloomberg-parity-upgrade-design.md

Builds the frontend and runs Vitest tests. Ensures no TypeScript or build errors and that unit tests pass.

```bash
# Frontend
cd frontend && npm run build                     # 0 TS/build errors
cd frontend && npm test                          # 0 Vitest failures
```

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

### GET /api/v1/crypto/search

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/API_V1.md

Searches for supported cryptocurrency instruments based on a query.

```APIDOC
## GET /api/v1/crypto/search

### Description
Searches supported crypto instruments.

### Method
GET

### Endpoint
/api/v1/crypto/search

### Parameters
#### Path Parameters
None

#### Query Parameters
- **q** (string) - Required - The search query for cryptocurrencies (e.g., 'btc').

### Response
#### Success Response (200)
(Response structure not detailed in source, but expected to contain a list of matching crypto instruments)

#### Response Example
(Example response not provided in source)
```

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

### Run Frontend Production Build

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/plans/2026-02-21-public-commit-prep.md

Builds the frontend application using npm and Vite. Expected output includes a successful build message and no TypeScript errors.

```bash
npm run build --prefix frontend 2>&1 | tail -20
```

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

### Run End-to-End Tests

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/README.md

Navigates to the frontend directory and executes end-to-end tests using npm.

```bash
npm run test:e2e
```

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

### Verify Backend Health

Source: https://github.com/hitheshkaranth/openterminalui/wiki/Getting-Started

Command to check the health of the backend API after installation.

```bash
curl http://localhost:8000/api/health
```

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

### GET /api/v1/equity/overview/top-tickers

Source: https://github.com/hitheshkaranth/openterminalui/blob/main/docs/API_V1.md

Retrieves top-bar indicators for crude oil, gold, and silver.

```APIDOC
## GET /api/v1/equity/overview/top-tickers

### Description
Returns top-bar indicators for:
- crude
- gold
- silver

### Method
GET

### Endpoint
/api/v1/equity/overview/top-tickers

### Parameters
None

### Response
#### Success Response (200)
(Response structure not detailed in source)

#### Response Example
(Example response not provided in source)
```