axiodb 19.1.1 → 20.3.2

package/README.md

@@ -1,19 +1,24 @@
-# AxioDB: The Pure JavaScript Alternative to SQLite
+# AxioDB: SQLite Alternative for JavaScript
 
 [![npm version](https://badge.fury.io/js/axiodb.svg)](https://badge.fury.io/js/axiodb)
+[![npm version shields](https://img.shields.io/npm/v/axiodb?logo=npm&label=npm)](https://www.npmjs.com/package/axiodb)
 [![npm downloads total](https://img.shields.io/npm/dt/axiodb.svg)](https://www.npmjs.com/package/axiodb)
 [![npm downloads yearly](https://img.shields.io/npm/dy/axiodb.svg)](https://www.npmjs.com/package/axiodb)
 [![npm downloads weekly](https://img.shields.io/npm/dw/axiodb.svg)](https://www.npmjs.com/package/axiodb)
 [![npm downloads monthly](https://img.shields.io/npm/dm/axiodb.svg)](https://www.npmjs.com/package/axiodb)
+[![install size](https://img.shields.io/npm/unpacked-size/axiodb?label=install%20size)](https://www.npmjs.com/package/axiodb)
+[![jsDelivr hits](https://img.shields.io/jsdelivr/npm/hm/axiodb?label=jsDelivr)](https://www.jsdelivr.com/package/npm/axiodb)
+[![npm types](https://img.shields.io/npm/types/axiodb?label=types)](https://www.npmjs.com/package/axiodb)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 [![Push to Registry](https://github.com/nexoral/AxioDB/actions/workflows/Push.yml/badge.svg?branch=main)](https://github.com/nexoral/AxioDB/actions/workflows/Push.yml)
 [![CodeQL](https://github.com/nexoral/AxioDB/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/nexoral/AxioDB/actions/workflows/github-code-scanning/codeql)
 [![Socket Security](https://socket.dev/api/badge/npm/package/axiodb)](https://socket.dev/npm/package/axiodb)
+[![GitHub Stars](https://img.shields.io/github/stars/nexoral/AxioDB?style=social)](https://github.com/nexoral/AxioDB)
 
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
 [![Tested on Node.js](https://img.shields.io/badge/tested%20on-20%20%7C%2021%20%7C%2022%20%7C%2023%20%7C%2024%20%7C%2025%20%7C%2026-blue)](https://github.com/nexoral/AxioDB/actions/workflows/Push.yml)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue)](https://www.typescriptlang.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue)](https://www.typescriptlang.org/)
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20native-success)](https://www.npmjs.com/package/axiodb)
 
 👉 **[Official Documentation](https://axiodb.in/)**: Access full guides, examples, and API references.
@@ -156,6 +161,8 @@ const db = new AxioDB({
 
 ### Querying
 - **Chainable Query API:** `.query()`, `.Sort()`, `.Limit()`, `.Skip()`, `.setCount()`, `.setProject()`, `.exec()` / `.findOne()`
+- **Index Hints:** `.hint('fieldName')` to force a specific index on any query for predictable performance
+- **Batch Read:** `.findByIds(['id1', 'id2'])` to retrieve multiple documents by ID in a single call
 - **MongoDB-style Query Operators:** `$gt`, `$gte`, `$lt`, `$lte`, `$ne`, `$in`, `$nin`, `$exists`, `$regex`, `$or`, `$and`
 - **Aggregation Pipelines:** 60+ MongoDB-compatible stages (`$match`, `$group`, `$sort`, `$project`, `$limit`, `$skip`, `$unwind`, `$addFields`, `$lookup`, `$facet`, `$bucket`, `$count`, `$sample`, ...) with full expression evaluator, cross-collection `$lookup` joins, and custom operator registration via `OperatorRegistry`
 - **Bulk Operations:** high-performance `insertMany`, `UpdateMany`, `deleteMany`
@@ -170,14 +177,23 @@ const db = new AxioDB({
 ### Transactions
 - **ACID-compliant, single-collection transactions** with savepoints, rollback, and Write-Ahead Logging (WAL) for crash recovery
 - **Session Management:** scoped transactions with timeout support
+- **TCP Transactions:** BEGIN/COMMIT/ROLLBACK over TCP with savepoints, connection-pinned client proxy, and auto-rollback on disconnect
 
 ```javascript
+// Local transaction
 const session = collection.startSession();
 await session.withTransaction(async (tx) => {
   await tx.insert({ name: 'Alice', balance: 1000 });
-  await tx.update({ name: 'Bob' }, { $inc: { balance: -100 } });
+  // Updates are flat merges; AxioDB does not implement MongoDB's $inc operator.
+  await tx.update({ name: 'Bob' }, { balance: 900 });
   // Auto-commits on success, auto-rolls-back on error
 });
+
+// TCP transaction
+const tx = await client.db('mydb').collection('users').beginTransaction();
+await tx.insert({ name: 'Alice', balance: 1000 });
+await tx.update({ name: 'Bob' }, { balance: 900 });
+await tx.commit(); // or await tx.rollback();
 ```
 
 ### Caching
@@ -211,7 +227,7 @@ await session.withTransaction(async (tx) => {
 - **🔄 Zero Code Changes:** same `createDB`/`createCollection`/`insert`/`query` API as embedded AxioDB
 - **⚡ Fast Binary Protocol:** length-prefixed JSON framing, with automatic reconnection
 - **🔐 Optional Authentication:** shared RBAC with the GUI, per-IP rate limiting (see [Advanced](#advanced-tcp-authentication) below)
-- **📦 35+ Commands:** full CRUD, aggregation, and indexing over the wire
+- **📦 32 Commands:** full CRUD, aggregation, indexing, and transactions over the wire
 - **🔁 Auto-Reconnect:** exponential backoff, up to 10 retry attempts
 - **💓 Heartbeat Monitoring:** `PING`/`PONG` every 30 seconds
 - **🆔 Request Correlation:** UUID-based request/response matching
@@ -371,12 +387,17 @@ irm https://raw.githubusercontent.com/nexoral/AxioDB/main/cli/Scripts/install.ps
 
 ### Usage
 
+> **Activation notice:** Data commands (`db`/`collection`/`document`/`index`/`transaction`/`ping`/`health`/`connect`) require the server started with `TCP: true` (`AXIODB_TCP=true`, port 27019). Management commands (`user`/`role`/`user change-password`/`export`/`import`) require `GUI: true`/`HTTP: true` (`AXIODB_GUI=true`, port 27018). TCP is data-plane only — no management over TCP by design.
+
 **Single commands:**
 ```bash
 axiodb -c axiodb://127.0.0.1:27019 ping
 axiodb -c axiodb://127.0.0.1:27019 db list
 axiodb -c axiodb://127.0.0.1:27019 document insert '{"name":"Alice"}' --db mydb --collection users
 axiodb -c axiodb://127.0.0.1:27019 document query '{}' --db mydb --collection users
+axiodb -c axiodb://127.0.0.1:27019 document query '{}' --hint email --db mydb --collection users
+axiodb -c axiodb://127.0.0.1:27019 health
+axiodb -c axiodb://127.0.0.1:27019 transaction begin --db mydb --collection users
 ```
 
 **Interactive REPL (MongoDB shell style):**
@@ -412,9 +433,36 @@ axiodb import ./backups/mydb.tar.gz --http-host localhost --http-port 27018 -u a
 # Tab completes .tar.gz file paths
 ```
 
+**User and role administration (via HTTP API):**
+```bash
+axiodb user list --http-host localhost --http-port 27018 -u admin -p secret
+axiodb user create analyst analyst123 View --http-host localhost --http-port 27018 -u admin -p secret
+axiodb user change-password oldPass newPass --http-host localhost --http-port 27018 -u analyst -p analyst123
+axiodb role list --http-host localhost --http-port 27018 -u admin -p secret
+axiodb role create Auditor document:view,document:query --http-host localhost --http-port 27018 -u admin -p secret
+```
+
+**Transactions (via TCP, full lifecycle):**
+```bash
+# File-based batch (auto-commit/rollback)
+axiodb transaction run operations.json --db mydb --collection users
+# Manual control
+axiodb transaction begin --db mydb --collection users  # → transactionId
+axiodb transaction savepoint <txnId> sp1
+axiodb transaction rollback-to <txnId> sp1
+axiodb transaction release <txnId> sp1
+axiodb transaction commit <txnId>
+axiodb transaction rollback <txnId>
+```
+
+Management commands use the authenticated HTTP API; they do not add management commands to the
+TCP client protocol, which remains focused on database, collection, document, index, aggregation,
+count, and transaction operations.
+
 ### Features
 
-- **All 23 commands:** database, collection, document CRUD, aggregation, indexing, export, import
+- **TCP data operations:** database, collection, document CRUD, aggregation, indexing, counts, and transactions
+- **CLI transactions and diagnostics:** run a transaction operation file, use query index hints, find documents by IDs, and check TCP health
 - **Interactive REPL:** MongoDB shell syntax (`use`, `show dbs`, `db.coll.find()`)
 - **Export & Import:** backup/restore databases via HTTP API, tab-completes file paths
 - **TLS support:** `--tls`, `--tls-cert`, `--tls-skip-verify`
@@ -645,7 +693,7 @@ volumes:
 ## 🤖 MCP Server — AI Agent Integration
 
 Spin up the same Docker container with `AXIODB_MCP=true` and let Claude (or any MCP-compatible
-AI agent) talk to your AxioDB instance directly — 32 tools covering databases, collections,
+AI agent) talk to your AxioDB instance directly — 43 tools covering databases, collections,
 documents, aggregation, indexes, dashboard stats, and user/role management, all gated by the
 same RBAC as the web GUI. It runs in the same process as your existing container; nothing new
 to install, no second database instance.
@@ -804,17 +852,21 @@ const electronics = await products
 
 - `createDB(dbName: string): Promise<Database>`
 - `deleteDatabase(dbName: string): Promise<SuccessInterface | ErrorInterface>`
+- `isDatabaseExists(dbName: string): Promise<boolean>`
+- `getInstanceInfo(): Promise<SuccessInterface | undefined>`
 
 ### Database
 
 - `createCollection(name: string): Promise<Collection>`
 - `deleteCollection(name: string): Promise<SuccessInterface | ErrorInterface>`
+- `isCollectionExists(name: string): Promise<boolean>`
 - `getCollectionInfo(): Promise<SuccessInterface>`
 
 ### Collection
 
 - `insert(document: object): Promise<SuccessInterface | ErrorInterface>`
-- `insertMany(documents: object[]): Promise<SuccessInterface | ErrorInterface>`
+- `insertMany(documents: object | object[]): Promise<SuccessInterface | ErrorInterface>`
+- `totalDocuments(): Promise<SuccessInterface | ErrorInterface>`
 - `query(query: object): Reader`
 - `update(query: object): Updater`
 - `delete(query: object): Deleter`
@@ -828,6 +880,8 @@ const electronics = await products
 
 `update(query)` and `delete(query)` on their own don't change anything — they return a chainable object. Call one of the methods below to actually apply the change:
 
+Updates are flat shallow merges. AxioDB does not implement MongoDB update operators such as `$inc`, `$set`, or `$push`; keys beginning with `$` are stored as ordinary field names.
+
 - `updater.UpdateOne(data: object): Promise<SuccessInterface | ErrorInterface>` — applies `data` to the first document matching `query`
 - `updater.UpdateMany(data: object): Promise<SuccessInterface | ErrorInterface>` — applies `data` to every document matching `query`
 - `deleter.deleteOne(): Promise<SuccessInterface | ErrorInterface>` — deletes the first document matching `query`
@@ -860,7 +914,7 @@ await collection.delete({ status: 'inactive' }).deleteMany();
 ### Transaction (Session)
 
 - `startSession(options?: { timeout?: number }): Session`
-- `session.withTransaction(callback: Function): Promise<any>`
+- `session.withTransaction(callback: (transaction: Transaction) => Promise<void>): Promise<SuccessInterface | ErrorInterface>`
 - `session.startTransaction(): Transaction`
 - `transaction.insert(document: object): Transaction`
 - `transaction.update(query: object, update: object): Transaction`
@@ -868,7 +922,30 @@ await collection.delete({ status: 'inactive' }).deleteMany();
 - `transaction.savepoint(name: string): Transaction`
 - `transaction.rollbackToSavepoint(name: string): Transaction`
 - `transaction.commit(): Promise<SuccessInterface>`
-- `transaction.rollback(): Promise<void>`
+- `transaction.rollback(): Promise<SuccessInterface | ErrorInterface>`
+
+### MCP transactions (Docker image)
+
+The Docker-only MCP server exposes authenticated, single-collection ACID transactions with
+insert, update, delete, savepoint, commit, and rollback tools. Begin with
+`axiodb_begin_transaction`, then pass its `transactionId` to the other transaction tools.
+
+### TCP Transaction Proxy
+
+- `collection.beginTransaction(): Promise<TransactionProxy>`
+- `transactionProxy.insert(data: object): Promise<unknown>`
+- `transactionProxy.insertMany(documents: object[]): Promise<unknown>`
+- `transactionProxy.query(query: object, options?): Promise<unknown>`
+- `transactionProxy.findByIds(ids: string[]): Promise<unknown>`
+- `transactionProxy.updateById(documentId: string, updateData: object): Promise<unknown>`
+- `transactionProxy.updateByQuery(query: object, updateData: object, updateOne?: boolean): Promise<unknown>`
+- `transactionProxy.deleteById(documentId: string): Promise<unknown>`
+- `transactionProxy.deleteByQuery(query: object, deleteOne?: boolean): Promise<unknown>`
+- `transactionProxy.savepoint(name: string): Promise<unknown>`
+- `transactionProxy.rollbackToSavepoint(name: string): Promise<unknown>`
+- `transactionProxy.releaseSavepoint(name: string): Promise<unknown>`
+- `transactionProxy.commit(): Promise<unknown>`
+- `transactionProxy.rollback(): Promise<unknown>`
 
 ---
 

package/cli/VERSION

@@ -1 +1 @@
-18.1.4
+20.3.2

package/cli/cmd/auth_management.go

@@ -0,0 +1,68 @@
+package cmd
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/nexoral/axiodb-cli/internal/config"
+	"github.com/nexoral/axiodb-cli/pkg/httpclient"
+	"github.com/spf13/cobra"
+)
+
+var userCmd = &cobra.Command{Use: "user", Short: "Manage HTTP API users"}
+var roleCmd = &cobra.Command{Use: "role", Short: "Manage HTTP API roles"}
+
+func httpClientFor(cmd *cobra.Command) (*config.Config, *httpclient.HTTPClient, error) {
+	cfg, err := config.FromFlags(cmd)
+	if err != nil { return nil, nil, err }
+	if cfg.Username == "" || cfg.Password == "" { return nil, nil, fmt.Errorf("--username and --password are required for HTTP administration") }
+	client := cfg.NewHTTPClient()
+	if err := client.Login(cfg.Username, cfg.Password); err != nil { return nil, nil, err }
+	return cfg, client, nil
+}
+
+var userListCmd = &cobra.Command{Use: "list", Short: "List users", RunE: func(cmd *cobra.Command, args []string) error {
+	cfg, client, err := httpClientFor(cmd); if err != nil { return err }; result, err := client.ListUsers(); if err != nil { return err }; return printOutput(cfg.Output, result)
+}}
+
+var userCreateCmd = &cobra.Command{Use: "create <username> <password> <role>", Short: "Create a user", Args: cobra.ExactArgs(3), RunE: func(cmd *cobra.Command, args []string) error {
+	cfg, client, err := httpClientFor(cmd); if err != nil { return err }; result, err := client.CreateUser(args[0], args[1], args[2]); if err != nil { return err }; return printOutput(cfg.Output, result)
+}}
+
+var userRoleCmd = &cobra.Command{Use: "set-role <username> <role>", Short: "Change a user's role", Args: cobra.ExactArgs(2), RunE: func(cmd *cobra.Command, args []string) error {
+	cfg, client, err := httpClientFor(cmd); if err != nil { return err }; result, err := client.UpdateUserRole(args[0], args[1]); if err != nil { return err }; return printOutput(cfg.Output, result)
+}}
+
+var userResetCmd = &cobra.Command{Use: "reset-password <username> <password>", Short: "Reset a user's password", Args: cobra.ExactArgs(2), RunE: func(cmd *cobra.Command, args []string) error {
+	cfg, client, err := httpClientFor(cmd); if err != nil { return err }; result, err := client.ResetUserPassword(args[0], args[1]); if err != nil { return err }; return printOutput(cfg.Output, result)
+}}
+
+var userDeleteCmd = &cobra.Command{Use: "delete <username>", Short: "Delete a user", Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error {
+	cfg, client, err := httpClientFor(cmd); if err != nil { return err }; result, err := client.DeleteUser(args[0]); if err != nil { return err }; return printOutput(cfg.Output, result)
+}}
+
+var userChangePasswordCmd = &cobra.Command{Use: "change-password <currentPassword> <newPassword>", Short: "Change own password (self-service)", Long: "Change your own password. Requires HTTP API (port 27018) to be enabled on the server (GUI/HTTP). Uses PATCH /api/auth/change-password.", Args: cobra.ExactArgs(2), RunE: func(cmd *cobra.Command, args []string) error {
+	cfg, client, err := httpClientFor(cmd); if err != nil { return err }; result, err := client.ChangeOwnPassword(args[0], args[1]); if err != nil { return err }; return printOutput(cfg.Output, result)
+}}
+
+var roleListCmd = &cobra.Command{Use: "list", Short: "List roles", RunE: func(cmd *cobra.Command, args []string) error {
+	cfg, client, err := httpClientFor(cmd); if err != nil { return err }; result, err := client.ListRoles(); if err != nil { return err }; return printOutput(cfg.Output, result)
+}}
+
+var roleCreateCmd = &cobra.Command{Use: "create <name> <permission,...>", Short: "Create a role", Args: cobra.ExactArgs(2), RunE: func(cmd *cobra.Command, args []string) error {
+	cfg, client, err := httpClientFor(cmd); if err != nil { return err }; permissions := strings.Split(args[1], ","); result, err := client.CreateRole(args[0], permissions); if err != nil { return err }; return printOutput(cfg.Output, result)
+}}
+
+var roleDeleteCmd = &cobra.Command{Use: "delete <name>", Short: "Delete a role", Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error {
+	cfg, client, err := httpClientFor(cmd); if err != nil { return err }; result, err := client.DeleteRole(args[0]); if err != nil { return err }; return printOutput(cfg.Output, result)
+}}
+
+var rolePermissionsCmd = &cobra.Command{Use: "permissions", Short: "List available permissions", RunE: func(cmd *cobra.Command, args []string) error {
+	cfg, client, err := httpClientFor(cmd); if err != nil { return err }; result, err := client.ListPermissions(); if err != nil { return err }; return printOutput(cfg.Output, result)
+}}
+
+func init() {
+	userCmd.AddCommand(userListCmd, userCreateCmd, userRoleCmd, userResetCmd, userDeleteCmd, userChangePasswordCmd)
+	roleCmd.AddCommand(roleListCmd, roleCreateCmd, roleDeleteCmd, rolePermissionsCmd)
+	rootCmd.AddCommand(userCmd, roleCmd)
+}

package/cli/cmd/document.go

@@ -101,11 +101,13 @@ var documentQueryCmd = &cobra.Command{
 		skip, _ := cmd.Flags().GetInt("skip")
 		sortStr, _ := cmd.Flags().GetString("sort")
 		findOne, _ := cmd.Flags().GetBool("find-one")
+		hint, _ := cmd.Flags().GetString("hint")
 
 		opts := commands.QueryOptions{
 			Limit:   limit,
 			Skip:    skip,
 			FindOne: findOne,
+			Hint:    hint,
 		}
 
 		if len(args) > 0 {
@@ -138,6 +140,35 @@ var documentQueryCmd = &cobra.Command{
 	},
 }
 
+var documentFindByIDsCmd = &cobra.Command{
+	Use:   "find-by-ids <ids-json>",
+	Short: "Find multiple documents by ID",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		cfg, err := config.FromFlags(cmd)
+		if err != nil {
+			return err
+		}
+		if cfg.DB == "" || cfg.Collection == "" {
+			return fmt.Errorf("--db and --collection flags are required")
+		}
+		var ids []string
+		if err := json.Unmarshal([]byte(args[0]), &ids); err != nil || len(ids) == 0 {
+			return fmt.Errorf("ids must be a non-empty JSON array of strings")
+		}
+		client, err := cfg.ConnectAndAuth()
+		if err != nil {
+			return err
+		}
+		defer client.Disconnect()
+		resp, err := commands.FindDocumentsByIDs(client, cfg.DB, cfg.Collection, ids)
+		if err != nil {
+			return err
+		}
+		return printOutput(cfg.Output, resp)
+	},
+}
+
 var documentGetCmd = &cobra.Command{
 	Use:   "get <id>",
 	Short: "Get a document by ID",
@@ -358,6 +389,7 @@ func init() {
 	documentQueryCmd.Flags().Int("skip", 0, "Skip results")
 	documentQueryCmd.Flags().String("sort", "", "Sort JSON (e.g., '{\"name\":1}')")
 	documentQueryCmd.Flags().Bool("find-one", false, "Find single document")
+	documentQueryCmd.Flags().String("hint", "", "Index field name to use")
 
 	documentUpdateByQueryCmd.Flags().Bool("many", false, "Update multiple documents")
 	documentDeleteByQueryCmd.Flags().Bool("many", false, "Delete multiple documents")
@@ -366,6 +398,7 @@ func init() {
 	documentCmd.AddCommand(documentInsertManyCmd)
 	documentCmd.AddCommand(documentQueryCmd)
 	documentCmd.AddCommand(documentGetCmd)
+	documentCmd.AddCommand(documentFindByIDsCmd)
 	documentCmd.AddCommand(documentUpdateCmd)
 	documentCmd.AddCommand(documentUpdateByQueryCmd)
 	documentCmd.AddCommand(documentDeleteCmd)

package/cli/cmd/health.go

@@ -0,0 +1,19 @@
+package cmd
+
+import (
+	"github.com/nexoral/axiodb-cli/internal/config"
+	"github.com/nexoral/axiodb-cli/pkg/commands"
+	"github.com/spf13/cobra"
+)
+
+var healthCmd = &cobra.Command{
+	Use: "health", Short: "Check AxioDB service health",
+	RunE: func(cmd *cobra.Command, _ []string) error {
+		cfg, err := config.FromFlags(cmd); if err != nil { return err }
+		client, err := cfg.ConnectAndAuth(); if err != nil { return err }; defer client.Disconnect()
+		response, err := commands.Health(client); if err != nil { return err }
+		return printOutput(cfg.Output, response)
+	},
+}
+
+func init() { rootCmd.AddCommand(healthCmd) }

package/cli/cmd/transaction.go

@@ -0,0 +1,191 @@
+package cmd
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+
+	"github.com/nexoral/axiodb-cli/internal/config"
+	"github.com/nexoral/axiodb-cli/pkg/commands"
+	"github.com/spf13/cobra"
+)
+
+var transactionCmd = &cobra.Command{
+	Use:   "transaction",
+	Short: "Run ACID transaction operations",
+	Long:  "ACID transactions over TCP (port 27019). Requires TCP server enabled (AXIODB_TCP=true). Use 'transaction run' for file-based batch, or begin/commit/rollback/savepoint for manual control.",
+}
+
+var transactionRunCmd = &cobra.Command{
+	Use:   "run <operations-json-file>",
+	Short: "Run a transaction from a JSON operation list",
+	Long:  "Run a full transaction from a JSON file. Requires TCP (AXIODB_TCP=true) and --db/--collection. Auto-commits on success, auto-rollbacks on failure.",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		cfg, err := config.FromFlags(cmd)
+		if err != nil {
+			return err
+		}
+		if cfg.DB == "" || cfg.Collection == "" {
+			return fmt.Errorf("--db and --collection flags are required")
+		}
+		content, err := os.ReadFile(args[0])
+		if err != nil {
+			return fmt.Errorf("read transaction file: %w", err)
+		}
+		var steps []commands.TransactionStep
+		if err := json.Unmarshal(content, &steps); err != nil {
+			return fmt.Errorf("invalid transaction JSON: %w", err)
+		}
+		client, err := cfg.ConnectAndAuth()
+		if err != nil {
+			return err
+		}
+		defer client.Disconnect()
+		response, err := commands.RunTransaction(client, cfg.DB, cfg.Collection, steps)
+		if err != nil {
+			return err
+		}
+		return printOutput(cfg.Output, response)
+	},
+}
+
+var transactionBeginCmd = &cobra.Command{
+	Use:   "begin",
+	Short: "Begin a transaction (returns transactionId)",
+	Long:  "Begin a transaction on --db/--collection. Requires TCP. Returns transactionId for subsequent commit/rollback/savepoint calls.",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		cfg, err := config.FromFlags(cmd)
+		if err != nil {
+			return err
+		}
+		if cfg.DB == "" || cfg.Collection == "" {
+			return fmt.Errorf("--db and --collection flags are required")
+		}
+		client, err := cfg.ConnectAndAuth()
+		if err != nil {
+			return err
+		}
+		defer client.Disconnect()
+		resp, err := commands.BeginTransaction(client, cfg.DB, cfg.Collection)
+		if err != nil {
+			return err
+		}
+		return printOutput(cfg.Output, resp)
+	},
+}
+
+var transactionCommitCmd = &cobra.Command{
+	Use:   "commit <transactionId>",
+	Short: "Commit a transaction",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		cfg, err := config.FromFlags(cmd)
+		if err != nil {
+			return err
+		}
+		client, err := cfg.ConnectAndAuth()
+		if err != nil {
+			return err
+		}
+		defer client.Disconnect()
+		resp, err := commands.CommitTransaction(client, args[0])
+		if err != nil {
+			return err
+		}
+		return printOutput(cfg.Output, resp)
+	},
+}
+
+var transactionRollbackCmd = &cobra.Command{
+	Use:   "rollback <transactionId>",
+	Short: "Rollback a transaction",
+	Args:  cobra.ExactArgs(1),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		cfg, err := config.FromFlags(cmd)
+		if err != nil {
+			return err
+		}
+		client, err := cfg.ConnectAndAuth()
+		if err != nil {
+			return err
+		}
+		defer client.Disconnect()
+		resp, err := commands.RollbackTransaction(client, args[0])
+		if err != nil {
+			return err
+		}
+		return printOutput(cfg.Output, resp)
+	},
+}
+
+var transactionSavepointCmd = &cobra.Command{
+	Use:   "savepoint <transactionId> <name>",
+	Short: "Create a savepoint",
+	Args:  cobra.ExactArgs(2),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		cfg, err := config.FromFlags(cmd)
+		if err != nil {
+			return err
+		}
+		client, err := cfg.ConnectAndAuth()
+		if err != nil {
+			return err
+		}
+		defer client.Disconnect()
+		resp, err := commands.Savepoint(client, args[0], args[1])
+		if err != nil {
+			return err
+		}
+		return printOutput(cfg.Output, resp)
+	},
+}
+
+var transactionRollbackToCmd = &cobra.Command{
+	Use:   "rollback-to <transactionId> <name>",
+	Short: "Rollback to a savepoint",
+	Args:  cobra.ExactArgs(2),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		cfg, err := config.FromFlags(cmd)
+		if err != nil {
+			return err
+		}
+		client, err := cfg.ConnectAndAuth()
+		if err != nil {
+			return err
+		}
+		defer client.Disconnect()
+		resp, err := commands.RollbackToSavepoint(client, args[0], args[1])
+		if err != nil {
+			return err
+		}
+		return printOutput(cfg.Output, resp)
+	},
+}
+
+var transactionReleaseCmd = &cobra.Command{
+	Use:   "release <transactionId> <name>",
+	Short: "Release a savepoint",
+	Args:  cobra.ExactArgs(2),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		cfg, err := config.FromFlags(cmd)
+		if err != nil {
+			return err
+		}
+		client, err := cfg.ConnectAndAuth()
+		if err != nil {
+			return err
+		}
+		defer client.Disconnect()
+		resp, err := commands.ReleaseSavepoint(client, args[0], args[1])
+		if err != nil {
+			return err
+		}
+		return printOutput(cfg.Output, resp)
+	},
+}
+
+func init() {
+	transactionCmd.AddCommand(transactionRunCmd, transactionBeginCmd, transactionCommitCmd, transactionRollbackCmd, transactionSavepointCmd, transactionRollbackToCmd, transactionReleaseCmd)
+	rootCmd.AddCommand(transactionCmd)
+}

package/cli/cmd/version.go

@@ -6,7 +6,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-var cliVersion = "18.1.4"
+var cliVersion = "20.3.2"
 
 var versionCmd = &cobra.Command{
 	Use:   "version",

package/cli/pkg/commands/document.go

@@ -42,6 +42,7 @@ type QueryOptions struct {
 	Skip     int
 	Sort     interface{}
 	FindOne  bool
+	Hint     string
 }
 
 func QueryDocuments(client *protocol.Client, dbName, collectionName string, opts QueryOptions) (*protocol.Response, error) {
@@ -64,6 +65,9 @@ func QueryDocuments(client *protocol.Client, dbName, collectionName string, opts
 	if opts.FindOne {
 		params["findOne"] = true
 	}
+	if opts.Hint != "" {
+		params["hint"] = opts.Hint
+	}
 
 	resp, err := client.Send("QUERY_DOCUMENTS", params)
 	if err != nil {
@@ -90,6 +94,21 @@ func QueryByID(client *protocol.Client, dbName, collectionName, id string) (*pro
 	return resp, nil
 }
 
+func FindDocumentsByIDs(client *protocol.Client, dbName, collectionName string, ids interface{}) (*protocol.Response, error) {
+	resp, err := client.Send("FIND_BY_IDS", map[string]interface{}{
+		"dbName":         dbName,
+		"collectionName": collectionName,
+		"ids":            ids,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("find documents by ids: %w", err)
+	}
+	if resp.StatusCode >= 400 {
+		return nil, fmt.Errorf("find documents by ids failed: %s", resp.Error)
+	}
+	return resp, nil
+}
+
 func UpdateDocumentByID(client *protocol.Client, dbName, collectionName, id string, updateData interface{}) (*protocol.Response, error) {
 	resp, err := client.Send("UPDATE_DOCUMENT_BY_ID", map[string]interface{}{
 		"dbName":         dbName,

package/cli/pkg/commands/health.go

@@ -0,0 +1,18 @@
+package commands
+
+import (
+	"fmt"
+
+	"github.com/nexoral/axiodb-cli/pkg/protocol"
+)
+
+func Health(client *protocol.Client) (*protocol.Response, error) {
+	resp, err := client.Send("HEALTH", nil)
+	if err != nil {
+		return nil, fmt.Errorf("get health: %w", err)
+	}
+	if resp.StatusCode >= 400 {
+		return nil, fmt.Errorf("get health failed: %s", resp.Error)
+	}
+	return resp, nil
+}