malloyyo

CLI to publish Malloy models to a Malloyyo instance.

It bundles up the .malloy files in a directory plus malloy-config.json, records the git commit they came from, and pushes them to a Malloyyo deployment. The server compiles and introspects the model — the CLI needs no database connection.

Install

The package is published as @malloydata/malloyyo; the command it installs is malloyyo. Needs Node ≥ 20.

npm i -g @malloydata/malloyyo     # then: malloyyo --help
# …or run without installing:
npx @malloydata/malloyyo --help

From source

It lives in the malloyyo monorepo as packages/cli.

# from the repo root
npm install
npm run build -w @malloydata/malloyyo   # → packages/cli/dist/index.js

# put `malloyyo` on your PATH (symlink to the built CLI)
cd packages/cli && npm link                # then: malloyyo --help

# …or just run it directly, no link
node packages/cli/dist/index.js --help

Configure

Add a malloyyo block to your malloy-config.json (or a standalone malloyyo.json). One entry per deployment. Only the env-var name is committed — never the token value.

{
  "connections": { /* … */ },
  "malloyyo": {
    "main":    { "url": "https://malloyyo.example.com",         "dataset": "mdw",
                 "malloyyo_token": { "env": "malloyyo_main_token" } },
    "staging": { "url": "https://malloyyo-staging.example.com", "dataset": "mdw_staging",
                 "malloyyo_token": { "env": "malloyyo_staging_token" } }
  }
}

Sign in

malloyyo login main                         # a named target from the config
malloyyo login https://malloyyo.example.com # a raw URL (no config needed)
malloyyo login                              # omit it if the config has one target
malloyyo logout main

Login is per-instance (it authenticates you to a URL, for all datasets on it), so the argument is a target or URL, not a dataset — and it's optional when the config is unambiguous. It asks the instance for two permissions, which the consent screen names: publishing models, and querying them. (A claude.ai connection to the same instance asks only to query, so it cannot publish — and a login stored before publishing had a permission of its own needs one more malloyyo login to gain it.) It uses the instance's OAuth flow (Authorization Code + PKCE, loopback redirect) and stores a refreshable token in ~/.config/malloyyo/credentials.json (mode 0600), keyed by instance URL — so you can be logged in to several instances at once. Tokens auto-refresh.

Use

malloyyo publish main           # push the model in . to the "main" target
malloyyo publish staging ./model
malloyyo publish main --dry-run # show what would be sent
malloyyo status main            # what's live: version, commit, compile state

The target dataset must already exist; publishing to a missing one fails rather than inventing it (a config typo would otherwise spawn junk datasets). To provision it from the CLI instead of the UI, opt in explicitly:

malloyyo publish main --create-dataset   # create the dataset if it isn't there yet

The dataset is created only after the model compiles, so a rejected publish still creates nothing, and it is created private — visibility is a deliberate act in the UI, and publishing never changes it. On an existing dataset the flag does nothing: you just get the next version. The dataset name comes from the target's dataset in the config, and must already be a valid name (lowercase letters, digits, underscores) — the CLI won't silently create it under a slugified variant that later publishes wouldn't find.

publish exits non-zero on a server-side compile failure, so it's safe to gate CI on.

API tokens (MALLOYYO_TOKEN)

For CI, or anywhere there is no browser to sign in with. Mint one in the instance's UI — your name → tokens, or <instance-url>/settings/tokens — and hand it over in the environment:

export MALLOYYO_TOKEN=myo_main_…
malloyyo publish            # no login, no browser, no --token

Every member of an instance can mint their own; you do not have to be an admin. A token is shown once, at creation — it is stored hashed, so a lost one is revoked and replaced rather than recovered. It carries the scopes you tick:

Scope	What it opens
publish	malloyyo publish and malloyyo status
mcp	querying the instance's published models over MCP

A token never carries more than you do. Publishing works on datasets you own (admins may publish to any), creating a dataset with --create-dataset stays admin-only, and every request re-checks your account — so revoking the token, or the account, takes effect on the next request rather than at expiry. Expiry is your choice at mint time, including never: a credential that lapses on its own breaks the pipeline at the worst moment, and the token list shows when each was last used so a forgotten one is still visible.

Token precedence: --token flag → the malloyyo_token env var named in the config → $MALLOYYO_TOKEN → your malloyyo login session. The config's own variable wins over MALLOYYO_TOKEN because someone publishing to two instances from one shell needs a credential per instance, and one variable can only hold one of them. Both variables sit above the stored login, so an export in your shell profile quietly shadows malloyyo login — login warns when that variable is set, and any auth failure names the source it used.

See API tokens for the CI recipe, rotation, and a troubleshooting table, and docs/model-publishing-design.md in the repo for the publish design.

Malloyyo-hosted instances (malloyyo cloud)

For instances Malloyyo runs for you. Everything above works the same on one — a hosted instance is a URL you login to and publish at — and these commands are how you get one and configure it.

malloyyo cloud instance create acme    # provision acme.malloyyo.com, wait for it to come up
malloyyo cloud instance list
malloyyo cloud instance status acme
malloyyo cloud instance delete acme    # reversible until it is destroyed

Name the instance the way you already know it — acme, the name in its URL and the one you malloyyo login to. Its ID works too, and is the one to use for an instance that has been fully destroyed, since its name is free for someone else to take.

create prints each provisioning step as it finishes and ends with the URL to sign in at, which is the same URL you then malloyyo login. It provisions real infrastructure, so it takes minutes; if the command stops waiting, the work continues and instance status picks it up. Every command takes --json for a parseable answer instead of progress lines.

Warehouse secrets

The credentials your Malloy models resolve connections from — the values behind { "env": "NAME" } in malloy-config.json. Several in one command are applied together, and the command returns once they are live (your instance restarts briefly).

malloyyo cloud secrets set acme PG_HOST=db.example.com PG_USER=app PG_PASSWORD
op read op://vault/pg/password | malloyyo cloud secrets set acme --stdin

A value typed as NAME=value lands in your shell history and is visible in ps while the command runs, so there are two ways not to type one: a bare NAME is prompted for with the input hidden, and --stdin reads NAME=value lines from a file, a CI variable, or a password manager. NAME=value stays for the parts that are not secrets — a host, a port, a user. Values are write-only: nothing in this CLI, and no endpoint behind it, reads one back.

Credentials

malloyyo cloud authenticates with a machine credential Malloyyo issues when your account is created, read from the environment:

export MALLOYYO_CLIENT_ID=...
export MALLOYYO_CLIENT_SECRET=...

That is the whole of it — there is nothing else to configure.

It is separate from the two instance credentials — malloyyo login and $MALLOYYO_TOKEN, both of which authenticate you to one instance. This one identifies your account to Malloyyo itself, and each command trades it for a short-lived access token carrying only the permissions that command needs: a list cannot create, and only secrets set can write secrets. The trade happens against Malloyyo's own API, so the CLI talks to nothing else. Your secret is held in memory for that request and is never logged, printed, or written to disk.

MALLOYYO_API_URL overrides the built-in API address; you should not need to set it.