nexoralnexoral/AxioDB/cli/AGENTS.md

AxioDB / cli

AGENTS.md35 starsChanged 9 days agoMITView on GitHub

Global rules live in ../AGENTS.md. This file only adds cli/ specifics — read the root first. Role — a standalone Go binary (axiodb) that talks to a running AxioDB server over the TCP protocol (27019), plus a MongoDB-style interactive REPL and a serve command that boots an isolated temporary local server. Zero relation to the npm build; it is cross-compiled and released separately. Go 1.22 · module github.com/nexoral/axiodb-cli · Cobra (commands) · chzyer/readline (REPL) · google/uuid. Cross-platform binaries are built…

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,843 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository12 other files it gives its agents.
- AGENTS.mdAGENTS.md
- Docker/AGENTS.mdAGENTS.md
- Document/AGENTS.mdAGENTS.md
- electron/AGENTS.mdAGENTS.md
- Email/AGENTS.mdAGENTS.md
- GUI/AGENTS.mdAGENTS.md
- Scripts/AGENTS.mdAGENTS.md
- source/AGENTS.mdAGENTS.md
- Test/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- skillSkill

The file

We split this AGENTS.md into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Never print secrets — the -u/-p flags, connection strings, and TLS material must not be echoed.
line 45
Very specific:
Default TCP port is 27019.
line 47

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

cli/ — AxioDB CLI (Agent Instructions)

Global rules live in ../AGENTS.md. This file only adds cli/ specifics — read the root first.

Role — a standalone Go binary (axiodb) that talks to a running AxioDB server over the TCP protocol (27019), plus a MongoDB-style interactive REPL and a serve command that boots an isolated temporary local server. Zero relation to the npm build; it is cross-compiled and released separately.

Stack

Go 1.22 · module github.com/nexoral/axiodb-cli · Cobra (commands) · chzyer/readline (REPL) · google/uuid.

Layout

main.go              → cmd.Execute()
cmd/                 cobra commands: root.go, connect.go, db.go, collection.go, document.go,
                     index.go, transaction.go, auth_management.go, health.go, ping.go,
                     serve.go (+ serve_test.go), db_export.go, db_import.go, version.go
pkg/protocol/        wire protocol — client.go, message.go, auth.go
pkg/commands/        command implementations — db, collection, document, index, transaction, health
pkg/httpclient/      HTTP client for export/import against 27018
pkg/serve/           launcher.go, runtime.go, mode.go (+ *_test.go) — local temp server
internal/config/     config.go
Scripts/             install.sh, install.ps1 — user installers (shipped in releases)
VERSION              plain-text version (single source)

Commands

cd cli
go build -o bin/axiodb .    # local build (VERSION is injected by ldflags in release, see below)
go test ./...               # unit tests (serve_test.go, launcher_test.go, mode_test.go)
go vet ./...

Cross-platform binaries are built by Scripts/BinBuilder.sh and .github/workflows/Push.yml (12 platforms) with the version stamped in:

-ldflags "-X github.com/nexoral/axiodb-cli/cmd.cliVersion=$VERSION"

Hard rules

cli/VERSION is the one source of truth; cmd/version.go's var cliVersion must match it in source (the release build overrides it via ldflags). Both are in the 13-place version list.
Never print secrets — the -u/-p flags, connection strings, and TLS material must not be echoed.
Respect the global flags in cmd/root.go (-c/--connection-string, --host, --port, --tls*, -o json|table, --timeout, --db, --collection, --http-*) rather than inventing ad-hoc ones.
Default TCP port is 27019; export/import HTTP defaults to 27018. serve seeds admin/admin (mirrors source/config/Keys/Permissions.ts) — never change that pairing without changing the core.
Scripts/install.sh / install.ps1 are user-facing and versioned; keep them in sync with VERSION.

Version sync (this folder)

cli/VERSION (plain text) and cli/cmd/version.go (var cliVersion) — both updated by Scripts/versionController.sh.

Done for this folder

go build ./... and go test ./... pass; go vet clean
New flags/commands documented and mirrored in the release notes flow if user-facing
cli/VERSION and cli/cmd/version.go match root when releasing

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free