### Install and Run Mongorai Globally

Source: https://github.com/psychosynthesis/mongorai/blob/main/README.md

Install Mongorai globally using npm and start it from your terminal. This is the quickest way to get started.

```bash
npm install -g mongorai

mongorai start
```

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

### Manual Build and Run

Source: https://github.com/psychosynthesis/mongorai/blob/main/README.md

Steps to manually build and run Mongorai from its source code. This involves installing server dependencies, building the frontend and backend, and then starting the server.

```bash
# Install the dependencies for server
npm install

# Build the front
cd front
npm run install
npm run build

# And the back
cd ..
npm run build

# Then run server
npm run server
```

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

### Install and Run Mongorai Locally

Source: https://github.com/psychosynthesis/mongorai/blob/main/README.md

Clone the repository, install dependencies, and run the server locally. This method is suitable for development or if you prefer to manage the project within your own environment.

```bash
npm i
npm run server
```

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

### Start Mongorai Server Programmatically

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Import and start the Mongorai server programmatically. Ensure './server.js' is correctly imported. Handles startup errors by logging and exiting.

```typescript
import { start } from './server.js';

// Start the Mongorai server
async function main() {
  try {
    await start();
    console.log('Mongorai server is running');
  } catch (error) {
    console.error('Failed to start Mongorai:', error);
    process.exit(1);
  }
}

main();
```

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

### Install Mongorai Globally

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Installs the Mongorai CLI tool globally on your system using npm.

```bash
# Install globally
npm install -g mongorai
```

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

### Start Mongorai Server

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Launches the Mongorai server. Use flags for authentication, custom passwords, or daemonization with PM2/Forever.

```bash
# Start in foreground mode
mongorai start
```

```bash
# Start with Basic Auth enabled
mongorai start --auth
```

```bash
# Start with custom password
mongorai start --auth --pass='your_strong_pass'
```

```bash
# Start as a daemon using PM2
mongorai start --pm2
```

```bash
# Start as a daemon using Forever
mongorai start --forever
```

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

### Build and Develop Mongorai from Source

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Clone the repository, install dependencies, and build/run both the frontend and backend. Frontend development can be run in a separate terminal.

```bash
# Clone the repository
git clone https://github.com/Psychosynthesis/Mongorai.git
cd Mongorai

# Install server dependencies
npm install

# Build and run the frontend
cd front
npm install
npm run build

# Build and run the backend
cd ..
npm run build
npm run server

# For frontend development (run in separate terminal)
cd front
npm run dev
```

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

### Run Mongorai with PM2 or Forever

Source: https://github.com/psychosynthesis/mongorai/blob/main/README.md

Start Mongorai as a daemon process using process managers like PM2 or Forever for background execution and automatic restarts.

```bash
mongorai start --pm2
# or
mongorai start --forever
```

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

### Get a Single Document

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Retrieves a single document by its MongoDB ObjectId from a specified collection.

```APIDOC
## GET /api/servers/{server}/databases/{database}/collections/{collection}/documents/{documentId}

### Description
Retrieves a specific document from a collection using its unique ObjectId.

### Method
GET

### Endpoint
`/api/servers/{server}/databases/{database}/collections/{collection}/documents/{documentId}`

### Parameters
#### Path Parameters
- **documentId** (string) - Required - The ObjectId of the document to retrieve.

### Request Example
```bash
curl -X GET "http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections/users/documents/507f1f77bcf86cd799439011"
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **document** (object) - The retrieved document.

#### Response Example
```json
{
  "ok": true,
  "document": {
    "_id": {"$oid": "507f1f77bcf86cd799439011"},
    "name": "John Doe",
    "email": "john@example.com",
    "status": "active",
    "createdAt": {"$date": "2024-01-15T10:30:00.000Z"},
    "profile": {
      "age": 30,
      "city": "New York"
    }
  }
}
```
```

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

### Get a Single Document by ID

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Retrieves a single document by its MongoDB ObjectId from a specified collection. Ensure the provided ID is a valid MongoDB ObjectId.

```bash
# Get document by ID
curl -X GET "http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections/users/documents/507f1f77bcf86cd799439011"
```

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

### Development Mode for Frontend

Source: https://github.com/psychosynthesis/mongorai/blob/main/README.md

Run the frontend in development mode using `npm run dev` in the `front` directory while the server is running. This allows for live updates during frontend development.

```bash
npm run dev
```

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

### Enable Basic Authentication

Source: https://github.com/psychosynthesis/mongorai/blob/main/README.md

Enable HTTP Basic Authentication for Mongorai by setting the MONGORAI_ENABLE_AUTH environment variable to true or using the --auth flag. The default credentials are 'mongorai' for username and 'default-pass' for password.

```bash
mongorai start --auth
```

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

### Configure Mongorai Server via Environment Variables

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Customize Mongorai's server behavior using environment variables for hosts, port, database file location, timeouts, and security settings.

```bash
# Set custom MongoDB hosts (semicolon-separated)
export MONGORAI_DEFAULT_HOST="mongodb://user:password@localhost:27017;localhost:27017"
```

```bash
# Change the server port (default: 3100)
export MONGORAI_SERVER_PORT=8000
```

```bash
# Custom hosts database file location (default: $HOME/.mongorai.db)
export MONGORAI_DATABASE_FILE="/tmp/mongorai.db"
```

```bash
# Timeout for document count operations in milliseconds (default: 5000)
export MONGORAI_COUNT_TIMEOUT=1000
```

```bash
# Enable read-only mode (disables write operations)
export MONGORAI_READ_ONLY_MODE=true
```

```bash
# Enable Basic Auth
export MONGORAI_ENABLE_AUTH=true
```

```bash
# Set Basic Auth password (default: 'default-pass')
export MONGORAI_PASS='your_secure_password'
```

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

### List All MongoDB Servers

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Fetches a list of all configured MongoDB servers, including their databases and statistics. Supports Basic Authentication.

```bash
# Get all servers
curl -X GET http://localhost:3100/api/servers

# With Basic Auth enabled
curl -X GET http://localhost:3100/api/servers \
  -u mongorai:your_password

# Response
[
  {
    "name": "localhost:27017",
    "size": 458752000,
    "databases": [
      {
        "name": "myapp",
        "size": 204800,
        "dataSize": 150000,
        "avgObjSize": 512,
        "storageSize": 180000,
        "totalIndexSize": 24800,
        "empty": false,
        "collections": []
      }
    ]
  }
]
```

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

### Configure Mongorai with Environment Variables

Source: https://github.com/psychosynthesis/mongorai/blob/main/README.md

Customize Mongorai's behavior by setting environment variables. This includes specifying default hosts, server port, database file location, count timeout, and read-only mode.

```bash
# Use some customized default hosts (Default = localhost:27017)
MONGORAI_DEFAULT_HOST="mongodb://user:password@localhost:27017;localhost:27017"

# Use another port. (Default = 3100)
MONGORAI_SERVER_PORT=8000

# Use a specific file to store hosts (Default = $HOME/.mongorai.db)
MONGORAI_DATABASE_FILE="/tmp/mongorai.db"

# Timeout before falling back to estimated documents count in ms (Default = 5000)
MONGORAI_COUNT_TIMEOUT=1000

# Read-only mode
MONGORAI_READ_ONLY_MODE=true
```

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

### List Databases on a Server

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Retrieves all databases on a specified MongoDB server, including their sizes and collection statistics.

```bash
# Get databases for a specific server
curl -X GET http://localhost:3100/api/servers/localhost:27017/databases

# Response
[
  {
    "name": "admin",
    "size": 40960,
    "dataSize": 32768,
    "avgObjSize": 256,
    "storageSize": 36864,
    "totalIndexSize": 4096,
    "empty": false,
    "collections": [...] 
  },
  {
    "name": "myapp",
    "size": 204800,
    "dataSize": 150000,
    "avgObjSize": 512,
    "storageSize": 180000,
    "totalIndexSize": 24800,
    "empty": false,
    "collections": [...] 
  }
]
```

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

### Add a New MongoDB Server

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Adds a new MongoDB server connection to Mongorai. The server URL is persisted in the hosts database.

```bash
# Add a new MongoDB server
curl -X PUT http://localhost:3100/api/servers \
  -H "Content-Type: application/json" \
  -d '{"url": "mongodb://user:password@192.168.1.100:27017"}'

# Response
{
  "ok": true
}
```

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

### Set Custom Authentication Password

Source: https://github.com/psychosynthesis/mongorai/blob/main/README.md

If basic authentication is enabled, you can set a custom password using the MONGORAI_PASS environment variable or the --pass option. It is recommended to use a strong password.

```bash
mongorai start --auth --pass='your_strong_pass'
```

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

### Query Documents in a Collection

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Executes a query against a collection with support for filtering, projection, sorting, and pagination. Use this to retrieve specific documents based on criteria.

```bash
# Simple query - get first 20 documents
curl -X GET "http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections/users/query"
```

```bash
# Query with filter
curl -X GET "http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections/users/query?q=%7B%22status%22%3A%22active%22%7D"
```

```bash
# Full query with all parameters
# q = {"status":"active"}
# sort = {"createdAt":-1}
# project = {"name":1,"email":1}
# limit = 10
# skip = 0
curl -X GET "http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections/users/query" \
  --data-urlencode 'q={"status":"active"}' \
  --data-urlencode 'sort={"createdAt":-1}' \
  --data-urlencode 'project={"name":1,"email":1}' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'skip=0'
```

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

### List Collections in a Database

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Retrieves all collections within a specific database on a MongoDB server, providing detailed statistics.

```bash
# Get collections in a database
curl -X GET http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections
```

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

### Query Documents in a Collection

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Executes a query against a collection with support for filtering, projection, sorting, pagination (limit/skip), and returns matching documents.

```APIDOC
## GET /api/servers/{server}/databases/{database}/collections/{collection}/query

### Description
Retrieves documents from a collection based on specified query parameters.

### Method
GET

### Endpoint
`/api/servers/{server}/databases/{database}/collections/{collection}/query`

### Query Parameters
- **q** (string) - Optional - A JSON string representing the query filter. Example: `{"status":"active"}`
- **sort** (string) - Optional - A JSON string specifying the sort order. Example: `{"createdAt":-1}`
- **project** (string) - Optional - A JSON string specifying the fields to include or exclude. Example: `{"name":1,"email":1}`
- **limit** (integer) - Optional - The maximum number of documents to return.
- **skip** (integer) - Optional - The number of documents to skip from the beginning.

### Request Example
```bash
curl -X GET "http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections/users/query" \
  --data-urlencode 'q={"status":"active"}' \
  --data-urlencode 'sort={"createdAt":-1}' \
  --data-urlencode 'project={"name":1,"email":1}' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'skip=0'
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **results** (array) - An array of documents matching the query.

#### Response Example
```json
{
  "ok": true,
  "results": [
    {
      "_id": {"$oid": "507f1f77bcf86cd799439011"},
      "name": "John Doe",
      "email": "john@example.com",
      "status": "active",
      "createdAt": {"$date": "2024-01-15T10:30:00.000Z"}
    }
  ]
}
```
```

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

### Count Documents in a Collection

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Returns the count of documents matching a query. Uses estimated count for empty queries and exact count for filtered queries with a configurable timeout.

```bash
# Count all documents
curl -X GET "http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections/users/count?q=%7B%7D"
```

```bash
# Count with filter
curl -X GET "http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections/users/count" \
  --data-urlencode 'q={"status":"active"}'
```

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

### Update a Document

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Updates a document by its ObjectId. Supports full replacement or partial updates using the `partial=true` query parameter, which applies `$set` semantics.

```bash
# Full document replacement
curl -X POST "http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections/users/documents/507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe Updated",
    "email": "john.updated@example.com",
    "status": "active",
    "updatedAt": {"$date": "2024-01-20T12:00:00.000Z"}
  }'
```

```bash
# Partial update (only specified fields)
curl -X POST "http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections/users/documents/507f1f77bcf86cd799439011?partial=true" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "inactive",
    "updatedAt": {"$date": "2024-01-20T12:00:00.000Z"}
  }'
```

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

### Check Read-Only Mode Status

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Retrieves the current read-only status of the Mongorai server. This endpoint is useful for verifying if write operations are permitted.

```bash
# Check if read-only mode is enabled
curl -X GET http://localhost:3100/api/readonly

# Response
{
  "ok": true,
  "readOnly": false
}
```

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

### REST API Endpoints

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Mongorai provides a REST API for managing MongoDB servers, databases, collections, and documents.

```APIDOC
## GET /api/readonly

### Description
Returns whether the server is running in read-only mode, which disables all write operations (POST, PUT, DELETE on documents).

### Method
GET

### Endpoint
/api/readonly

### Request Example
```bash
curl -X GET http://localhost:3100/api/readonly
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success of the operation.
- **readOnly** (boolean) - True if read-only mode is enabled, false otherwise.

#### Response Example
```json
{
  "ok": true,
  "readOnly": false
}
```
```

```APIDOC
## GET /api/servers

### Description
Retrieves a list of all connected MongoDB servers with their databases and statistics.

### Method
GET

### Endpoint
/api/servers

### Parameters
#### Query Parameters
- **auth** (boolean) - Optional. If true, requires Basic Auth.

### Request Example
```bash
# Get all servers
curl -X GET http://localhost:3100/api/servers

# With Basic Auth enabled
curl -X GET http://localhost:3100/api/servers \
  -u mongorai:your_password
```

### Response
#### Success Response (200)
- **Array of server objects**
  - **name** (string) - The name or connection string of the server.
  - **size** (integer) - The total size of the server in bytes.
  - **databases** (Array of database objects)
    - **name** (string) - The name of the database.
    - **size** (integer) - The size of the database in bytes.
    - **dataSize** (integer) - The data size of the database in bytes.
    - **avgObjSize** (integer) - The average object size in the database.
    - **storageSize** (integer) - The storage size of the database in bytes.
    - **totalIndexSize** (integer) - The total size of indexes in the database.
    - **empty** (boolean) - True if the database is empty, false otherwise.
    - **collections** (Array) - List of collections in the database.

#### Response Example
```json
[
  {
    "name": "localhost:27017",
    "size": 458752000,
    "databases": [
      {
        "name": "myapp",
        "size": 204800,
        "dataSize": 150000,
        "avgObjSize": 512,
        "storageSize": 180000,
        "totalIndexSize": 24800,
        "empty": false,
        "collections": []
      }
    ]
  }
]
```
```

```APIDOC
## PUT /api/servers

### Description
Adds a new MongoDB server connection to Mongorai. The server URL is stored persistently in the hosts database.

### Method
PUT

### Endpoint
/api/servers

### Parameters
#### Request Body
- **url** (string) - Required - The connection URL of the MongoDB server.

### Request Example
```bash
curl -X PUT http://localhost:3100/api/servers \
  -H "Content-Type: application/json" \
  -d '{"url": "mongodb://user:password@192.168.1.100:27017"}'
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success of the operation.

#### Response Example
```json
{
  "ok": true
}
```
```

```APIDOC
## DELETE /api/servers/{serverName}

### Description
Removes a MongoDB server connection from Mongorai by its hostname.

### Method
DELETE

### Endpoint
/api/servers/{serverName}

### Parameters
#### Path Parameters
- **serverName** (string) - Required - The hostname or connection string of the server to remove.

### Request Example
```bash
curl -X DELETE http://localhost:3100/api/servers/localhost:27017
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success of the operation.

#### Response Example
```json
{
  "ok": true
}
```
```

```APIDOC
## GET /api/servers/{serverName}/databases

### Description
Retrieves all databases available on a specific MongoDB server with size and collection information.

### Method
GET

### Endpoint
/api/servers/{serverName}/databases

### Parameters
#### Path Parameters
- **serverName** (string) - Required - The hostname or connection string of the server.

### Request Example
```bash
curl -X GET http://localhost:3100/api/servers/localhost:27017/databases
```

### Response
#### Success Response (200)
- **Array of database objects**
  - **name** (string) - The name of the database.
  - **size** (integer) - The size of the database in bytes.
  - **dataSize** (integer) - The data size of the database in bytes.
  - **avgObjSize** (integer) - The average object size in the database.
  - **storageSize** (integer) - The storage size of the database in bytes.
  - **totalIndexSize** (integer) - The total size of indexes in the database.
  - **empty** (boolean) - True if the database is empty, false otherwise.
  - **collections** (Array) - List of collections in the database.

#### Response Example
```json
[
  {
    "name": "admin",
    "size": 40960,
    "dataSize": 32768,
    "avgObjSize": 256,
    "storageSize": 36864,
    "totalIndexSize": 4096,
    "empty": false,
    "collections": [
      ...
    ]
  },
  {
    "name": "myapp",
    "size": 204800,
    "dataSize": 150000,
    "avgObjSize": 512,
    "storageSize": 180000,
    "totalIndexSize": 24800,
    "empty": false,
    "collections": [
      ...
    ]
  }
]
```
```

```APIDOC
## GET /api/servers/{serverName}/databases/{dbName}/collections

### Description
Retrieves all collections within a specific database including detailed statistics like document count, size, and index information.

### Method
GET

### Endpoint
/api/servers/{serverName}/databases/{dbName}/collections

### Parameters
#### Path Parameters
- **serverName** (string) - Required - The hostname or connection string of the server.
- **dbName** (string) - Required - The name of the database.

### Request Example
```bash
curl -X GET http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections
```

### Response
#### Success Response (200)
- **Array of collection objects** (Details not provided in source text)

#### Response Example
(Response example not provided in source text)
```

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

### Remove a MongoDB Server

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Removes a MongoDB server connection from Mongorai using its hostname.

```bash
# Remove a server
curl -X DELETE http://localhost:3100/api/servers/localhost:27017

# Response
{
  "ok": true
}
```

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

### Count Documents in a Collection

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Returns the count of documents matching a query. Uses estimated count for empty queries (faster) and exact count for filtered queries with a configurable timeout.

```APIDOC
## GET /api/servers/{server}/databases/{database}/collections/{collection}/count

### Description
Retrieves the count of documents in a collection that match a given query.

### Method
GET

### Endpoint
`/api/servers/{server}/databases/{database}/collections/{collection}/count`

### Query Parameters
- **q** (string) - Optional - A JSON string representing the query filter. Example: `{"status":"active"}`

### Request Example
```bash
curl -X GET "http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections/users/count" \
  --data-urlencode 'q={"status":"active"}'
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **count** (integer) - The number of documents matching the query.

#### Response Example
```json
{
  "ok": true,
  "count": 150
}
```
```

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

### Update a Document

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Updates a document by its ObjectId. Supports full replacement or partial updates.

```APIDOC
## POST /api/servers/{server}/databases/{database}/collections/{collection}/documents/{documentId}

### Description
Updates an existing document in a collection. Can perform a full replacement or a partial update.

### Method
POST

### Endpoint
`/api/servers/{server}/databases/{database}/collections/{collection}/documents/{documentId}`

### Parameters
#### Path Parameters
- **documentId** (string) - Required - The ObjectId of the document to update.

#### Query Parameters
- **partial** (boolean) - Optional - If true, performs a partial update using `$set` semantics. Defaults to false (full replacement).

### Request Body
- **(object)** - Required - The document data to update or replace.

### Request Example
```bash
# Partial update (only specified fields)
curl -X POST "http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections/users/documents/507f1f77bcf86cd799439011?partial=true" \
  -H "Content-Type: application/json" \
  -d '{ 
    "status": "inactive",
    "updatedAt": {"$date": "2024-01-20T12:00:00.000Z"}
  }'
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **update** (object) - The updated document.

#### Response Example
```json
{
  "ok": true,
  "update": {
    "name": "John Doe Updated",
    "email": "john.updated@example.com",
    "status": "inactive",
    "updatedAt": {"$date": "2024-01-20T12:00:00.000Z"}
  }
}
```
```

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

### Delete a Document

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Deletes a single document by its ObjectId from the specified collection. This operation is disabled when running in read-only mode.

```bash
# Delete a document
curl -X DELETE "http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections/users/documents/507f1f77bcf86cd799439011"
```

```bash
# Error response in read-only mode
{
  "ok": false,
  "message": "You can't do this in read-only mode"
}
```

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

### Delete a Document

Source: https://context7.com/psychosynthesis/mongorai/llms.txt

Deletes a single document by its ObjectId from the specified collection. This operation is disabled when running in read-only mode.

```APIDOC
## DELETE /api/servers/{server}/databases/{database}/collections/{collection}/documents/{documentId}

### Description
Deletes a specific document from a collection using its ObjectId.

### Method
DELETE

### Endpoint
`/api/servers/{server}/databases/{database}/collections/{collection}/documents/{documentId}`

### Parameters
#### Path Parameters
- **documentId** (string) - Required - The ObjectId of the document to delete.

### Request Example
```bash
curl -X DELETE "http://localhost:3100/api/servers/localhost:27017/databases/myapp/collections/users/documents/507f1f77bcf86cd799439011"
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "ok": true
}
```

#### Error Response (e.g., read-only mode)
```json
{
  "ok": false,
  "message": "You can't do this in read-only mode"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.