CLI Reference

Dynoxide has four subcommands: serve (the default), mcp, import, and healthcheck.

Running dynoxide with no subcommand is the same as dynoxide serve, and the bare form accepts --host, --port, --db-path, --encryption-key-file and --schema directly. Those top-level flags exist only for that form. Combining one with an explicit subcommand is a parse error rather than a silent no-op:

dynoxide --port 8000                    # fine - bare form
dynoxide serve --port 8000              # fine - flag belongs to the subcommand
dynoxide --db-path data.db serve        # error: the flag is ignored, so it's rejected

serve

Starts the DynamoDB-compatible HTTP server.

dynoxide --port 8000
dynoxide serve --db-path data.db --port 8000

Pre-creating tables with --schema

--schema takes the same DescribeTable JSON that import --schema does, and creates each table in it on startup, skipping any that already exist. It pre-populates an empty database with the right structure without running an import first:

aws dynamodb describe-table --table-name Users > schema.json
dynoxide --schema schema.json --db-path dev.db

mcp

Starts the MCP (Model Context Protocol) server for coding agents. See the MCP docs for the full setup guide, including the bearer-token requirement on the HTTP transport.

dynoxide mcp
dynoxide mcp --http --port 19280

Stdio transport is the default. Use --http for the Streamable HTTP transport.

On serve these same flags carry an --mcp- prefix, because serve already owns --host and --port for the DynamoDB server.

import

Imports data from a DynamoDB Export (the S3 export format). Useful for creating local snapshots of production data. See the import guide for the anonymisation rules format and the export directory layout.

dynoxide import \
  --source ./export-data/ \
  --schema schema.json \
  --output snapshot.db

--source points at the directory of exported JSON files, and --schema takes DescribeTable JSON.

Anonymisation is built in - mask, hash, redact, or replace fields with fake data:

dynoxide import \
  --source ./export/ \
  --schema schema.json \
  --rules rules.toml \
  --output anonymised.db

The rules file is TOML. Available actions are fake, mask, hash, redact, and null. The import guide covers the format, the generator list, and how to keep a value consistent across tables.

healthcheck

Probes a running server for liveness. The Docker image uses it for its HEALTHCHECK directive, and it works as a Kubernetes readiness or liveness probe.

dynoxide healthcheck --port 8000

--host and --port also read DYNOXIDE_HEALTHCHECK_HOST and DYNOXIDE_HEALTHCHECK_PORT, so a container that overrides CMD can point the probe somewhere else with -e DYNOXIDE_HEALTHCHECK_PORT=....