namux

Namux is a small Go 1.25+ CLI that generates brandable business and domain names.

It is an independent open-source tool — not an official Namelix product. The default backend is an unofficial adapter around Namelix’s public generate endpoint (internal/namelix). Thanks to hexagonal design, that adapter is swappable.

Built for humans and AI assistants (Codex, Grok, Claude, OpenCode, Pi, etc.): stable JSON schema, predictable exit codes, and a schema command that documents the full input/output contract.

Version (single source of truth)

Artifact	Source
SemVer	root VERSION file only
Git tag	v + contents of VERSION (e.g. v0.1.0)
Binary namux version	ldflags from VERSION at build / GoReleaser tag
Codename	RELEASE_NAME (TAGtastic arabian_birds)

Never hardcode product SemVer in Go sources — the fallback is "dev" until ldflags inject the real value. make check-version enforces this.

Install

# Requires Go 1.25+
go install github.com/aenawi/namux/cmd/namux@latest
# pin a release:
go install github.com/aenawi/namux/cmd/namux@v0.1.0

# Or from this repo (reads VERSION + RELEASE_NAME)
make build
./namux version

Quick start

# Human-friendly table
./namux generate coffee shop --style brandable --ext com,io --available

# Machine-friendly JSON (ideal for agents)
./namux generate "fitness app" \
  --description "mobile workout tracker" \
  --style brandable \
  --random medium \
  --ext com,ai,io \
  --require-domains \
  --available \
  --limit 15 \
  --format json --pretty

# Names only
./namux gen saas tools --format plain

# CSV export
./namux generate organic skincare --format csv -o names.csv

Commands

Command	Purpose
generate (gen, g)	Generate names and print filtered results
styles	List name styles
extensions	List supported TLDs
schema	Print JSON contract (for AI agents)
version	Print CLI version

Bare keyword args default to generate:

./namux coffee shop --format json

Backend entry fields (request)

These map 1:1 to the Namelix web app POST /generate payload (current default backend):

Field	CLI flag	Default	Notes
keywords	positional / --keywords	(required)	Brand keywords
description	-d, --description	""	One-sentence product pitch
blacklist	--blacklist	""	Comma-separated forbidden tokens
max_length	--max-length	25	Preferred max letters (3–50)
style	--style	brandable	See styles below
random	--random	medium	low | medium | high
extensions	--ext	com	TLDs without dots; co-uk for .co.uk
require_domains	--require-domains / --no-domains	true	Domain availability check
page	--page	0	Zero-based page
num	--num	5	Batch size hint (1–20)
seed	--seed	random	Reproducibility across pages
category	--category	""	Optional, best with style=default
prev_names	(internal)	[]	Filled when --pages > 1
ban_history	(internal)	[]	Carried across multi-page fetches
saved	(internal)	[]	Liked names (backend learning signal)
premium_index	(internal)	0	Service placement offset

Styles

Value	Meaning
default	Mixed / auto
brandable	Invented brandables (Google, Rolex)
twowords	Evocative phrases (RedBull)
threewords	Short multi-word phrases
compound	Compounds (FedEx, Microsoft)
spelling	Alternate spelling (Lyft, Fiverr)
nonenglish	Non-English flavour
dictionary	Real words (Apple, Amazon)

Extensions

com, co, io, ai, app, org, net, ly, ca, au, co-uk, de, fr, nl, it, ch, pl, be, se, eu

Expected backend response

The Namelix adapter returns:

{
  "logos": [
    {
      "id": "logo-…",
      "businessName": "Brewvibe",
      "description": "Brewvibe",
      "hasDomain": true,
      "domains": "io, com",
      "page": -1,
      "…": "plus logo styling fields (palette, fonts, layout, …)"
    }
  ],
  "new_bans": []
}

Namux normalizes each logo into a lean result:

{
  "query": { "keywords": "coffee shop", "style": "brandable", "…" : "…" },
  "count": 1,
  "results": [
    {
      "name": "Brewvibe",
      "has_domain": true,
      "available_tlds": ["io", "com"],
      "domains": "io, com",
      "suggested_fqdns": ["brewvibe.io", "brewvibe.com"],
      "description": "Brewvibe",
      "id": "logo-…",
      "page": -1
    }
  ]
}

Use --include-raw to attach the last full backend payload under raw.

Client-side filters & output

Flag	Purpose
--available	Keep only has_domain=true
--filter-tld com,ai	Require availability on listed TLDs
--limit N	Cap results after filtering
--unique	De-duplicate names (default on)
--contains X	Name must contain substring
--exclude a,b	Drop names containing tokens
--min-name-length / --max-name-length	Length filters
--pages N	Fetch multiple pages
--format	table | json | csv | plain | ndjson
--pretty	Pretty JSON
-o file	Write to file

Exit codes (agent-friendly)

Code	Meaning
0	Success with ≥1 result
1	Runtime / API error
2	Usage / validation error
3	Success path but zero results after filters

JSON formats print errors as {"error":"…","code":N} on stderr.

Architecture

Hexagonal (ports & adapters), kept small (KISS):

cmd/namux            → process entry (product binary)
internal/cli         → driving adapter (flags, UX)
internal/service     → use cases (multi-page, filter)
internal/domain      → models + NameGenerator port
internal/namelix     → driven adapter (Namelix HTTP /generate)
internal/output      → table/json/csv/plain/ndjson

SOLID notes:

• S — packages split by responsibility (client vs filter vs render)
• O — new output formats / filters without touching the HTTP client
• L — any domain.NameGenerator can replace the Namelix adapter (tests use fakes)
• I — single-method port (Generate)
• D — service depends on the port, not the concrete HTTP client

Product name Namux ≠ backend package internal/namelix: the latter is only the adapter for namelix.com.

AI assistant usage

# Discover the contract
./namux schema

# Canonical agent invocation
./namux generate "KEYWORD IDEA" \
  --description "one sentence" \
  --style brandable \
  --random medium \
  --ext com,io,ai \
  --require-domains \
  --available \
  --limit 20 \
  --format json --pretty

Also see AGENTS.md.

Development

make tools          # gosec, govulncheck, golangci-lint, tagtastic
make hooks-install  # wire .githooks/pre-push (blocks dirty pushes)
make release-name   # TAGtastic codename (arabian_birds) → RELEASE_NAME
make verify         # fmt + vet + test + lint + build
make security       # gosec + govulncheck + gitleaks (report only)
make security-push  # push gate: gosec + gitleaks fail; govulncheck warns
make security-strict # release gate: all three fail on findings
make build
./namux version     # e.g. 0.1.0 (scrub-warbler) commit=… built=…

Pre-push runs make pre-push (= verify + security-push). See docs/local-checks.md.

Release codenames & publishing

Release names come from TAGtastic using the arabian_birds theme. They are baked into the binary at build time via RELEASE_NAME + ldflags.

# bump version (edit VERSION only), update CHANGELOG, then:
make release-name    # optional: new bird codename → RELEASE_NAME
make pre-push
git add -A && git commit -m "chore: release $(cat VERSION)"
make release         # tags v$(cat VERSION), pushes, GoReleaser → GitHub Release

Local multi-arch dry-run (no publish): make release-snapshot.

Disclaimer

Namux is not affiliated with, endorsed by, or an official product of Namelix.

This CLI optionally calls Namelix’s public web endpoints as used by namelix.com/app. There is no official public API documentation; domain availability is advisory. Be respectful of their service (avoid abusive request rates). Namelix branding and service belong to their respective owners.

License

MIT