s3v - S3 Vectors Shell Tools

A pure Bash CLI for Amazon S3 Vectors. Calls the S3 Vectors REST API directly with manual AWS SigV4 signing — no AWS SDK required.

Prerequisites

• curl 7.84+ (requires %header{} support)
• jq
• perl with Digest::SHA module

Verify dependencies:

./s3v check-deps

Installation

git clone <repo-url>
cd s3vectors-shell
chmod +x s3v

Optionally add to your PATH:

export PATH="$PWD:$PATH"

Usage

s3v <command> <action> [options]

Global Options

Option	Description
--region <region>	AWS region
--profile <profile>	AWS CLI profile
--output json|text	Output format (default: text)
--verbose	Enable debug output
--yes, -y	Skip confirmation prompts

Bucket Management

s3v bucket create --name my-bucket
s3v bucket list [--prefix <prefix>] [--all]
s3v bucket get --name my-bucket
s3v bucket delete --name my-bucket
s3v bucket count

Index Management

s3v index create --bucket my-bucket --name my-index --dimension 384 --metric cosine
s3v index list --bucket my-bucket [--all]
s3v index get --bucket my-bucket --name my-index
s3v index delete --bucket my-bucket --name my-index
s3v index count --bucket my-bucket

Vector Operations

# Put a single vector
s3v vector put --bucket my-bucket --index my-index --key doc-001 \
  --data '[0.1,0.2,0.3]' --metadata '{"title":"example"}'

# Batch put from file or stdin
s3v vector put-batch --bucket my-bucket --index my-index --file vectors.json
cat vectors.json | s3v vector put-batch --bucket my-bucket --index my-index

# Get vectors
s3v vector get --bucket my-bucket --index my-index --keys doc-001,doc-002 \
  --return-data --return-metadata

# List and count
s3v vector list --bucket my-bucket --index my-index [--all]
s3v vector count --bucket my-bucket --index my-index

# Delete
s3v vector delete --bucket my-bucket --index my-index --keys doc-001,doc-002

Similarity Query

s3v query --bucket my-bucket --index my-index \
  --vector '[0.1,0.2,0.3]' --top-k 10 \
  --filter '{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}' \
  --return-metadata

See Metadata Filtering for filter syntax.

Authentication

Credentials are resolved in order:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
2. AWS CLI profile (--profile or default)
3. EC2 instance metadata (IMDSv2)

Batch Vector Format

The put-batch command expects a JSON array:

[
  {
    "key": "doc-001",
    "data": { "float32": [0.1, 0.2, 0.3] },
    "metadata": { "title": "example" }
  }
]

MIT License

See LICENSE for details.