CLI Usage Guide¶

1. Tool Overview and Core Functions¶

1.1 Tool Introduction¶

GoVector CLI is the command-line interaction tool for GoVector vector database, providing lightweight, interactive vector data management capabilities. As one of GoVector's dual usage modes, the CLI tool allows you to complete core operations such as vector insertion, query, and deletion through the terminal without writing any Go code.

1.2 Core Features¶

Feature Category	Description
Vector Operations	Supports batch insert (Upsert), similarity search (Search), count statistics (Count), delete operations (Delete)
Collection Management	Provides collection list view (ls) function, supports multi-collection management
Service Mode	Built-in HTTP API server, provides Qdrant-compatible REST interfaces
Interactive Mode	Supports interactive TUI interface, suitable for quick testing and exploration
Parameter Abbreviations	All parameters support short abbreviations to improve operation efficiency

1.3 Differences from Embedded Mode¶

GoVector provides two usage modes:

Mode	Applicable Scenario	Characteristics
CLI Tool Mode	Quick testing, data management, daemon deployment	No code writing required, operate via command line
Embedded Library Mode	Deep integration into Go applications	Direct operation via Go API, zero network overhead

2. Installation and Environment Configuration¶

2.1 Installation Methods¶

Method 1: Homebrew Installation (Recommended)¶

brew tap DotNetAge/govector
brew install govector

After installation, the binary file is named govectord.

Method 2: Download Pre-built Package¶

Download compressed packages for your platform from the GitHub Releases page:

# macOS ARM64 (M1/M2/M3)
curl -O https://github.com/DotNetAge/govector/releases/download/v0.1.3/govector_v0.1.3_darwin_arm64.tar.gz
tar -xzf govector_v0.1.3_darwin_arm64.tar.gz
sudo mv govector /usr/local/bin/govector
chmod +x /usr/local/bin/govector

# Linux AMD64
curl -O https://github.com/DotNetAge/govector/releases/download/v0.1.3/govector_v0.1.3_linux_amd64.tar.gz
tar -xzf govector_v0.1.3_linux_amd64.tar.gz
sudo mv govector /usr/local/bin/govector
chmod +x /usr/local/bin/govector

Method 3: Build from Source¶

git clone https://github.com/DotNetAge/govector.git
cd govector
make build
# Compiled output is located at bin/govector

2.2 Environment Requirements¶

Environment Requirement	Minimum Version	Recommended Version
Go	1.20	1.21+
Memory	512 MB	2 GB+
Disk	100 MB	10 GB+

2.3 Verify Installation¶

govector --help

Successful installation will display help information.

3. Basic Command Syntax¶

3.1 Command Syntax Overview¶

govector <command> [dbfile] [options]

3.2 Available Commands¶

Command	Function Description	Syntax Example
`upsert`	Insert or update vector data	`govector upsert [dbfile] -j='[...]' -c='<collection>'`
`search`	Execute similarity search	`govector search [dbfile] -v='[...]' -l=<limit> -c='<collection>'`
`count`	Count vectors in collection	`govector count [dbfile] -c='<collection>'`
`delete`	Delete vectors by specified ID	`govector delete [dbfile] -i='[...]' -c='<collection>'`
`ls`	List all collections in database	`govector ls [dbfile]`
`rm`	Delete specified collection	`govector rm [dbfile] -c='<collection>'`
`serve`	Start HTTP API server	`govector serve -d=[dbfile] -p=<port>`

3.3 Interactive TUI Mode¶

Running govector [dbfile] directly will start the interactive interface:

govector [dbfile]

Interactive mode supports commands:

Command (upsert/search/count/delete/?/exit) >
// Use /? to view help

4. Detailed Command Parameters¶

4.1 upsert Command¶

Function: Insert or update vector data points. If dbfile is not specified, defaults to govector.db. If the specified database file or collection does not exist, the system will automatically create them (HNSW index enabled by default).

Required Parameters:

Parameter	Abbreviation	Description	Example
`--json`	`-j`	JSON format vector data	`-j='[{"id":"1","vector":[0.1,0.2],"payload":{}}]'`

Optional Parameters:

Parameter	Abbreviation	Default	Description
`--collection`	`-c`	`default`	Target collection name

Data Point JSON Structure:

{
  "id": "unique identifier",
  "vector": [0.1, 0.2, 0.3],
  "payload": {
    "key": "value"
  }
}

4.2 search Command¶

Function: Execute vector similarity search. If the specified database file or collection does not exist, the program will report an error and exit gracefully.

Required Parameters:

Parameter	Abbreviation	Description	Example
`--vector`	`-v`	Query vector (JSON array)	`-v='[0.1, 0.2, 0.3]'`

Optional Parameters:

Parameter	Abbreviation	Default	Description
`--limit`	`-l`	10	Maximum number of results
`--collection`	`-c`	`default`	Target collection name

4.3 count Command¶

Function: Count the number of vectors in the specified collection.

Optional Parameters:

Parameter	Abbreviation	Default	Description
`--collection`	`-c`	`default`	Target collection name

4.4 delete Command¶

Function: Delete vectors by specified ID.

Required Parameters:

Parameter	Abbreviation	Description	Example
`--ids`	`-i`	ID array to delete (JSON)	`-i='["id1","id2"]'`

Optional Parameters:

Parameter	Abbreviation	Default	Description
`--collection`	`-c`	`default`	Target collection name

4.5 ls Command¶

Function: List all collections in the database and their metadata.