Tooling

Onyx CLI

A cross-platform CLI for Onyx Cloud Database focused on schema management and multi-language code generation.

Install options

CLI

Homebrew (macOS)

brew tap OnyxDevTools/onyx-cli
brew install onyx-cli
onyx version

Homebrew upgrade

brew update
brew upgrade onyx-cli
onyx version

Script installer

curl -fsSL https://raw.githubusercontent.com/OnyxDevTools/onyx-cli/main/scripts/install.sh | bash

# or specific version
curl -fsSL https://raw.githubusercontent.com/OnyxDevTools/onyx-cli/main/scripts/install.sh | bash -s -- v0.1.0

Commands

CLI

Version

onyx version

Flag	Description
—	No flags.

Prints the CLI version string.

› onyx version

onyx version 0.11.14 (commit ae326fc, built 2026-02-02)

Info

onyx info

Flag	Description
—	No flags required.
--database-id	Override database ID.
--base-url	Override Database API base URL.
--api-key	Override API key.
--api-secret	Override API secret.
--ai-base-url	Override AI base URL.
--default-model	Override default model.
--config <path>	Use a specific config file (bypasses search chain).

Shows resolved config sources, config path, connection check (Schema API ping). Flags are optional overrides—see Credential & config resolution for defaults and search order.

› onyx info

databaseId:   bbabca0e-82ce-11f0-0000-a2ce78b61b6a (source: config:./onyx-database.json)
baseUrl:      https://api.onyx.dev (source: config:./onyx-database.json)
apiKey:       d80RkwNoK (source: config:./onyx-database.json)
apiSecret:    jlvK**************4DPq (source: config:./onyx-database.json)
aiBaseUrl:    https://ai.onyx.dev (source: default)
defaultModel: onyx (source: default)
codegenLang:  typescript (source: default)
configFile:   ./onyx-database.json

onyx init

Flag	Description
--schema <path>	Schema file to read (default `./api/onyx.schema.json`).
--out <dir>	Destination directory for generated Go types (default `./gen/onyx`).
--package <name>	Go package name to emit (default `onyx`).
--force	Overwrite existing `generate.go`.

Writes generate.go with go generate directive //go:generate onyx gen --go ....

Codegen

onyx gen

Flag	Description
--typescript / --ts	Emit TypeScript types + client.
--java	Emit Java bindings.
--kotlin / --kt	Emit Kotlin bindings.
--python / --py	Emit Python client.
--go / --golang	Emit Go client.
--source api\|file	Where to fetch schema (default `file`).
--schema <path>	Schema file path (default `./onyx.schema.json`).
--out <file\|dir>[,more]	Output target(s). Defaults: `./onyx/types.ts` (TS), `./onyx` (Python), `./gen/onyx` (Go).
--tables a,b	(API source) restrict to listed tables.
--name <type>	(TS) exported schema type name (default `OnyxSchema`).
--base <name>	(TS) base export name.
--package <name>	(Go) package name (default `onyx`).
--overwrite	Allow overwriting generated files (default on).
-q / --quiet	Suppress non-error logs.

If no language flag is provided, codegenLanguage in config or ONYX_CODEGEN_LANGUAGE is used (typescript/ts/java/kotlin/kt/python/py/go/golang). Outputs mirror canonical SDK generators (TS, Python, Go).

Example outputs

› onyx gen --ts

TypeScript types → ./onyx/types.ts

› onyx gen --kt

Kotlin data classes → kotlin/Onyx.kt

› onyx gen --py

Python client → ./onyx

› onyx gen --go

Go client → ./gen/onyx (package onyx)

Schema

Command	Flag	Description
onyx schema get [file]	--tables a,b	Print only selected tables to stdout.
onyx schema get [file]	--print	Prints schema to stdout instead of writing file.
onyx schema get [file]	—	Writes schema file; [file] is optional.
onyx schema get --out [file]	--out	Alternate explicit output path.
onyx schema publish [file]	—	Validate then publish schema.
onyx schema validate [file]	—	Validate schema locally; non-zero on errors.
onyx schema diff [file]	—	YAML diff vs API schema.
onyx schema info	—	Show resolved config and connection check.

If [file] is omitted, the CLI uses the language-specific default: TypeScript/Python ./onyx.schema.json; Go ./api/onyx.schema.json. Supply a path to override.

Example commands

› onyx schema get

Wrote schema to onyx.schema.json

› onyx schema get api/onyx.schema.json

Wrote schema to api/onyx.schema.json

› onyx schema validate

valid: true (source: onyx.schema.json)

› onyx schema diff

No differences found between API schema and onyx.schema.json

› onyx schema publish

Schema publish succeeded

Credential & config resolution

CLI

Resolution chain

explicit config → environment variables → ONYX_CONFIG_PATH → project config file → home profile

Environment variables

ONYX_DATABASE_ID
ONYX_DATABASE_BASE_URL
ONYX_DATABASE_API_KEY
ONYX_DATABASE_API_SECRET
Optional: ONYX_AI_BASE_URL
Optional: ONYX_DEFAULT_MODEL
Optional: ONYX_CODEGEN_LANGUAGE (defaults typescript; aliases ts/java/kotlin/kt/python/py/go/golang) — used when no language flag is provided to onyx gen

Config JSON keys

codegenLanguage optional (defaults typescript; same aliases as above). If no language flag is given, onyx gen uses this value.

Defaults

Base URL: https://api.onyx.dev
AI Base URL: https://ai.onyx.dev
Default model: onyx

Config file search order

If --config is provided, that path is used (errors if unreadable).
Else if ONYX_CONFIG_PATH is set, that path is used (errors if unreadable).
Otherwise, the first readable JSON config in order:
- ./onyx-database-<databaseId>.json
- ./onyx-database.json
- ./config/onyx-database-<databaseId>.json
- ./config/onyx-database.json
- ~/.onyx/onyx-database-<databaseId>.json
- ~/.onyx/onyx-database.json
- ~/onyx-database.json

Schema file conventions

CLI

Default schema file path: ./onyx.schema.json
onyx schema get overwrites the default file unless output is redirected via --print/--tables printing behavior.

Canonical references

CLI

TypeScript SDK (canonical CLI + credential semantics): github.com/OnyxDevTools/onyx-database
Onyx Cloud Console: cloud.onyx.dev
Onyx website: onyx.dev