itonics-cli

A fast Go CLI for the ITONICS Innovation OData v2 API. Manage elements, element types, files, attachments, watches and likes from your terminal or from AI agents (Claude Code, Codex CLI, Cursor, …).

The companion itonics-skills repo provides the agent skill that documents this CLI for LLM-based assistants.

brew tap itonics/itonics https://github.com/itonics/itonics-cli
brew install itonics

Until the first v* tag is released, the tap installs the --HEAD formula and builds from main.

scoop bucket add itonics https://github.com/itonics/itonics-cli
scoop install itonics

scoop update itonics pulls the next release.

Grab a release archive for your OS/arch from the latest release:

• macOS / Linux — itonics_X.Y.Z_<Os>_<arch>.tar.gz, extract itonics into ~/.local/bin
• Windows — itonics_X.Y.Z_Windows_x86_64.zip, extract itonics.exe into a directory on PATH

go install github.com/itonics/itonics-cli@latest

Or, working in a clone:

git clone https://github.com/itonics/itonics-cli.git
cd itonics-cli
go build -o itonics .

itonics login

Interactively prompts for the tenant domain, space URI, and API key (hidden input), validates them against the API, and writes them to ~/.config/itonics/config.toml with chmod 0600. Re-running login rotates the key — existing values are shown as defaults.

Non-interactive forms:

itonics login --domain https://acme.itonics.io --space SPACE_URI --api-key SECRET
echo "$KEY" | itonics login --domain ... --space ... --api-key -        # read key from stdin
itonics login ... --skip-check                                          # skip the validation round-trip

Other commands:

itonics whoami                                        # show which creds would be used, and from where
itonics logout                                        # delete ~/.config/itonics/config.toml

Credentials are resolved in this order (highest first):

1. ITONICS_DOMAIN / ITONICS_API_KEY / ITONICS_SPACE env vars — set by your shell, by --env-file, or by a .env in the current directory.
2. The persisted profile at ~/.config/itonics/config.toml.

See .env.example if you prefer the env-var path.

Run itonics --help or itonics <group> --help for the full surface.

import "github.com/itonics/itonics-cli/internal/api"

c := api.New("https://your-tenant.itonics.io", "your-api-key", "your-space-uri")
elements, err := c.ListElements(ctx, api.ListElementsParams{Filter: "elementTypeUri eq 'XXX'", RawFieldValues: true})
fileURI, err := c.UploadFile(ctx, "/path/to/logo.png", "user@example.com", "")
_, err = c.AttachFiles(ctx, "ELEMENT_URI", []string{fileURI}, "user@example.com")

Note: the API client lives under internal/ today — if you have a need for it as a public package, open an issue.

• The OpenAPI spec lives at apidocs.itonics-innovation.com (bundled-openapi.yaml).
• rawFieldValues=1 returns each property as {uri, type, label, rawValue}. rawValue is always an array.
• For rich_text properties, send plain HTML or base64:<base64-of-HTML>. The tiptap: storage encoding is read-only and rejected on writes.
• The pre-signed upload response advertises x-amz-acl: private, but the backing bucket has ACLs disabled. The CLI strips that header before PUTting the binary — replicate this when calling the API directly.
• Not every element type exposes a default Attachments field. When it doesn't, POST /elements/{uri}/attachments returns 400 BadRequestException: Element type 'X' does not expose the default Attachments field. Use a file / headerImage-typed element property instead.

Tagging vX.Y.Z triggers a GoReleaser workflow that builds binaries for macOS / Linux / Windows (amd64 + arm64), creates a GitHub release, publishes checksums, and updates Formula/itonics.rb so the tap installs the new version.

MIT — see LICENSE.