Every command below works with either a dip login session or an API key in the DIPPR_API_KEY environment variable, unless its own section says otherwise.
The CLI’s configuration variables were renamed from ALTIMATE_* to DIPPR_* (DIPPR_API_KEY, DIPPR_URL, DIPPR_REGISTRY, DIPPR_SLUG, DIPPR_MCP_RESOURCE, DIPPR_PLANE_ID, DIPPR_TENANT_ID). The CLI reads only these DIPPR_* names. An ALTIMATE_API_KEY exported for another product does not override your cached dip login session or produce a deprecation warning. The app SDK and MCP clients keep their separately configured ALTIMATE_* variables.
Read commands report unavailable data with diagnostics. dip engine list exits non-zero when no tenant’s engine inventory could be read; a partial inventory retains available rows and is explicitly labelled incomplete. Check each command’s warnings and status before treating missing rows as absent resources. Write commands exit non-zero when the requested change did not happen. Any command accepts --workspace <url> (or the DIPPR_URL environment variable) to pick which tenant it acts on. Leave it off and what happens depends on your credential:
  • With a dip login session: a read reports on every tenant you are signed in to, and a write needs exactly one. It refuses when you are signed in to several, naming them.
  • With an DIPPR_API_KEY: an API key belongs to exactly one tenant, so dip aims a command at that tenant rather than at every tenant you are signed in to. If exactly one login is cached, dip uses it directly. If several are cached and neither --workspace nor DIPPR_URL names one, dip works out which tenant the key belongs to by asking your signed-in tenants which one authenticates it. While it is still guessing it asks only over HTTPS, and only tenants that share a domain, so it will not present the key to a local dev or cross-domain origin. A read that resolves the key reports on just that tenant. It may be unresolvable for three reasons: the logins span different domains, none authenticates the key, or it is a legacy key minted before capability scopes (which carries no signal to probe). In that case a read falls back to reporting on every signed-in tenant, using each one’s own login rather than the key. Pass --workspace (or DIPPR_URL) to name the tenant.

Flags a command does not take

A command refuses a flag it does not take. It stops before it sends anything, names the flag and exits 1:
A mistyped flag is refused, not dropped: the example above registers nothing, where running without --capability would have registered the source with the default capabilities. Three commands have a preview mode: dip db load --dry-run, dip mcp install --dry-run and dip mcp uninstall --dry-run. No other command has one. A command that changes something in your tenant refuses --dry-run rather than running for real:
dip integration create has no preview either. Your tenant checks the fields when it registers the source, and dip integration delete removes a source you did not want. A few details:
  • A flag’s value that starts with - goes inline: --description=-internal. A name that starts with - (a database, for example) goes after a bare --: dip db status -- -scratch. The bare -- works for names only, not for a flag’s value. A single-dash spelling such as -yes is refused: dip flags take two dashes.
  • --no-<flag> is accepted for an on/off flag the command takes (--no-wait, --no-fill-types) and for nothing else. It takes no value: write --no-wait, or --wait=false.
  • The refusal is a usage error: with --json, on a command that lists --json, stdout carries the error document described under Errors and --json.
  • A flag that takes a value needs one. --content-type --dry-run is refused, because --dry-run would be read as the content type; write a value that really starts with -- as --flag=<value>.
  • These commands do not refuse an unknown flag and ignore one they do not read, --dry-run included, so dip skill uninstall --dry-run removes the skills: dip login, dip whoami, dip doctor, dip version, dip update, dip telemetry, dip skill, dip mcp list, dip mcp login, dip mcp token, dip db duckdb, dip app new, dip app dev, dip app build, and dip pipeline new, check, dev, build and sdk-sync. None of them changes a source, engine, database, grant or pipeline in your tenant. Some do contact it: dip login and dip mcp login sign in, dip mcp token renews a sign-in that is about to expire, and dip whoami, dip doctor and dip mcp list read from it. Check the spelling of --plane and --workspace on those, because a mistyped one falls back to the default.

Signing in

dip login

Opens your browser to sign in via OAuth and caches the resulting session. See Install dip and sign in for the full walkthrough. Needs: nothing (this is the sign-in step itself).

dip whoami

Lists every tenant you are signed in to, which user you are signed in as (your email, when the roster read is available to this sign-in, that is, a tenant admin who has used a governance command; otherwise your user id, such as user:<id>; --json always carries principal, such as user:<id>, and email when known), when each session expires, which capabilities you consented to on this machine, and what your credential cannot read at all. A sign-in made before a capability joined the default gets a missing line with the dip login command that adds it (missing_default_scopes in --json). A cached data plane token past its expiry says whether dip renews it on next use (renews in --json) instead of reading as broken; see Install dip and sign in. When a workspace pins a dip release (a beta), whoami compares your running version with that release. With no pinned release, it uses the published stable release. If the workspace release cannot be read, whoami says so instead of falling back to the stable release. A dev (unstamped) build, or any other version dip cannot order against a release tag, gets neither comparison — whoami says so and never suggests dip update, since it cannot tell whether that would be an upgrade or a downgrade. --offline makes no version request. For the catalogs attached to an engine, which whoami lists as console-only, use SHOW CATALOGS or the MCP browse tool with level catalogs to get the names you write in SQL: the console shows display names, which can differ. See Install dip and sign in. Needs: nothing beyond a cached session (or none — it still reports “not signed in”).

dip logout

Signs out of a tenant on this machine: revokes the sign-in and every cached MCP refresh token on the server, then removes the local session and cached MCP tokens. With one cached session, no URL is needed. With several, pass --workspace URL or --all; $DIPPR_URL also selects a tenant. Signing out again succeeds even when no session remains. Revocation is best-effort: local sign-out still completes if the server cannot be reached, and the output tells you to revoke the connection at /settings/connected-apps in the console. --offline skips revocation. --json reports removal, revocations and warnings without credentials. MCP registrations stay in your agents; logout lists the recorded registrations and prints the exact dip mcp uninstall --agent all --workspace URL command to remove them.

dip doctor

Groups checks by querying, building data apps, and publishing them. When no check has failed and you have a cached sign-in and the workspace answers, the human summary says so and points at dip engine list to see what you can query. When any check failed, the closing line counts the failed checks instead and “what to fix” lists the remedies it has; a failed check without one is only in the rows above. dip doctor does not run a query or check your engines. When the workspace has a usable shared MCP address (the OAuth-only https://mcp.<plane-domain> that dip mcp list shows), it prints it on a shared MCP host line for AI apps that cannot run dip; --json adds shared_mcp_url, and --offline leaves it out. Its dip row compares with the selected workspace’s beta release when pinned; an older build gets dip update --version <tag>. Otherwise it compares with the published stable release. A dev (unstamped) build cannot be ordered against either release, so the row says comparison is unavailable rather than suggesting dip update. The JSON probe statuses retain their original values. A sign-in made before a capability joined the default sign-in keeps an ok session row: the row names what the sign-in lacks and the dip login command that adds it, and the exit status does not change. Full walkthrough at Install dip and sign in. Needs: nothing.

Connecting your coding agent

dip mcp list

Lists one entry per data plane: the name dip would register the server under, its tenant-specific endpoint, a shared row with the OAuth-only address https://mcp.<plane-domain>, and the engines it serves. A plane with no query engine is still listed, with engines: [] in --json. JSON includes mcp_endpoint and mcp_shared_endpoint for each server. Client installation continues to use the tenant-specific address. Shared account sign-in must be enabled in your deployment before an OAuth client can use the shared address. You can register a plane’s MCP server for a new tenant and ask your AI to connect a source. Sample data needs a query engine on that plane, so the workspace_status tool offers it only once one exists. dip probes the tenant-specific and shared addresses separately, once each, with the same four-second timeout. An address that answers 404 or has a TLS certificate that does not cover it is unavailable. The tenant-specific address then shows no MCP server on this plane; an unavailable shared address shows shared MCP unavailable, followed by the reason. One address being available does not mean the other is available. In --json, mcp_available and mcp_unavailable_reason describe the tenant-specific address; mcp_shared_available and mcp_shared_unavailable_reason describe the shared address. Each reason is present whenever its availability is false, and omitted when it is true. A data plane whose domain starts with engine., apps., mcp., registry., duck. or app. has no shared MCP address: mcp_shared_endpoint is empty, mcp_shared_available is false, and the reason names that first label. dip does not probe a shared address for that plane; its tenant-specific address remains available to probe and use. A timeout or refused connection is inconclusive, so that address stays available. dip mcp install and dip mcp login use the tenant-specific availability to skip planes without MCP; dip mcp install says so in one line. Needs: a signed-in session or an API key.

dip mcp install

Registers this tenant’s MCP servers with the coding agents on this machine, then prints the shared OAuth-only MCP host (https://mcp.<plane-domain>) when there is a usable one; --json adds it as shared_mcp_url. Full detail at Install dip and sign in.
An agent already running when this registers something does not notice on its own — see If your agent was already running. The human output names the one action to take (restart, or for Cursor, reload the window) right after any registration it actually made; --json’s restart_required is the same fact for a script.
Needs: a signed-in session or an API key, to list the planes to register.

dip mcp uninstall

Removes what dip mcp install registered, and the Claude Code allow rule when dip added it, even when Claude Code is not installed any more. A rule you added yourself stays, and so does a choice you made with --no-allow-rule. Exits with an error when it cannot read Claude Code’s settings file. Same flags as install.

dip mcp login

Signs you in to one data plane’s MCP endpoint in the browser and saves the result, so dip mcp token can hand a token to an agent that has no browser. Run it once per data plane. The token can run SQL and browse catalogs (query_engines:execute_sql) and search (metadata:read). When the sign-in also grants a refresh token, dip mcp token keeps the token current; when it does not, the login says so, and you run dip mcp login again once the token expires. A sign-in that carries a refresh token survives a later dip login when both belong to the same user; otherwise that dip login removes it.

dip mcp token

Prints a valid MCP token for a data plane you signed in to with dip mcp login, refreshing it when it is close to expiring. Only the token goes to standard output, so export ALTIMATE_API_KEY=$(dip mcp token --plane NAME) captures it cleanly for Cursor or a script. A token expires 15 minutes after it was issued (--json shows expires_at), and a variable exported this way does not change in an agent that is already running, so re-export it and restart the agent when it expires. Codex does not need it: it signs in to the server itself and renews the sign-in. An explicit --plane must match exactly one live plane when the list is available, including after a rename. If the list cannot be read, an exact saved name, slug or id still works offline.

Agent skills

dip skill list

Shows what is bundled in this binary and which version of each skill is installed where.

dip skill install

Writes the bundled agent skills where a coding agent looks for them. Every installed file carries a marker naming the dip version that wrote it. Before running any command, dip compares that marker against its own version and rewrites files that differ — so a self-update, an explicit dip update, or even dip update --version <older-tag> keeps the skills on disk matching the binary you are running. A file with no marker is yours; dip never touches it. To customize a skill, copy it under a different name.

dip skill uninstall

Removes the files dip installed, and nothing else.

Data apps

dip app new

For TypeScript and single-page apps, run npm install in the generated directory to install dependencies and build the bundled SDK, then dip app check to check conformance. The bundled SDK README also includes commands for checking and rebuilding its source.
Scaffolds a ready-to-build app with the SDK vendored in. Choose python, streamlit or typescript for an app that queries certified metrics. Use frontend for a browser app that only runs SQL; its SDK has no semantic layer API. The Python scaffold’s requirements.txt includes pyarrow for .sql() and .query_metrics() results. Install it with python3 -m pip install -r requirements.txt in your virtual environment before running the app. See Build a data app for dependency setup and catalog discovery. The frontend scaffold is a static app. Its manifest declares staticRoot: "/app/dist", and its Dockerfile copies the built dist/ folder into an otherwise empty image, with no server of its own. Dippr serves those files itself and never runs the image. See Static apps. dip app dev runs it the same way as before. All four starters include permission-denial help. The Python, Streamlit and browser starters show Access needed; the TypeScript starter returns the message and PERMISSION_DENIED code in JSON. The message names a table only when the viewer can list it and uses the app owner’s display name when available. Unavailable names use generic wording. Existing apps need the updated SDK and republishing to receive this behavior. The frontend starter’s header shows Signed in as with the viewer’s email, when one is on record, and You see only the rows your access allows. Under each result it shows Data as of, the time that query finished. See Tell each viewer whose view it is. New apps include the SDK guide and app-design skill, with its stylesheet, reference patterns and design checker. The SDK guide also tells your agent to build a first-visit walkthrough for viewers, with a setting to turn it off. Ask your coding agent to use both skills when building the app. The frontend, typescript and python starters also include the design stylesheet, dippr-app.css, already connected: src/dippr-app.css (imported first) for frontend, public/dippr-app.css (served at /dippr-app.css) for typescript, and dippr-app.css (served and linked from the page) for python. Leave it unchanged and put your own layout CSS elsewhere. streamlit starters have no stylesheet; they use the theme file described in the skill. Starters made before this change do not have the file. Run dip app new --help or dip app new -h to see creation options. Help exits successfully without requiring a name or creating an app. The starter manifest declares one read capability for --catalog, or * for ordinary catalogs you can read, including Trino’s system catalog, but not workspace databases, when you omit the flag. The consent reason names this scope. Long catalog names remain complete in the declaration; only the name in the consent prose is shortened to keep the reason within 200 characters. The scaffold does not discover or choose a catalog for you. For a workspace database, name its catalog explicitly, for example dip app new --name my-app --runtime python --catalog probe_shop. The flag works the same way for all four runtimes. * does not cover a workspace database, even one you own. This declaration grants nothing extra by itself: the person using the app must also have access to the data. Narrow it to the catalogs, schemas and tables the app actually reads before you ship it. For a python or streamlit app, dip app new also writes a ready manifest.json next to the manifest source, so the very next step works with no Python installed. The file is byte-identical to what the SDK produces. After you edit the manifest source, run dip app check to re-materialize it (it uses Docker when your python3 is older than 3.10 or absent), so what gets registered stays in step with your source. dip app build and dip app push also refresh it first when your python3 is older than 3.10 or absent, so the label they bake is never stale. Needs: nothing (purely local).

dip app check

Runs the app’s conformance gate: manifest validity, drift between your manifest source and the committed manifest.json, and a scan that fails the check if you import a raw data-store driver (trino, psycopg2, snowflake, duckdb, and so on) — a second door into data with its own credential is exactly what the platform exists to remove. Needs: for a python or streamlit app, python3 3.10+, or Docker (when your python3 is older than 3.10 or absent, the check runs in the app’s own Python 3.12 image instead of stopping); for a typescript or frontend app, node/npm, with @altimate/app-sdk resolvable from the app directory — run npm install first on a fresh scaffold. A typescript/frontend app where Node cannot resolve the SDK (no npm install yet, or an interrupted one) is refused with a short remedy before the gate ever calls npm, rather than Node’s own ERR_MODULE_NOT_FOUND stack. Run dip app check --help or dip app check -h for a quick reminder of these flags: it prints the dip app command group’s summary (not this page) and exits successfully, without running the conformance gate.

dip app dev

Runs the app locally against your own tenant’s real engine — real rows — using only your dip login session. There is no API-key path for this command. viewer and roles that inherit it, including analyst, can preview their own app without publishing or installing it. Queries return only data allowed by both your own grants and the app’s declared capabilities, with your row filters and column masks applied. A viewer without data grants gains no access to rows. Another member cannot obtain query credentials for your preview or delete its sandbox. Single-page app starters enforce the installed browser policy locally, including blocking external API calls, CDN assets and arbitrary inline scripts. Vite allows only its exact React refresh preamble by hash for hot reload; its WebSocket uses the app’s own origin. dip app dev looks for the expected browser policy setting in your Vite configuration text. If it cannot find it, it prints a warning and continues starting your app. This is a best-effort hint: matching text in a comment or elsewhere in the configuration can suppress the warning even when your local pages have no browser policy. Add this line inside server in vite.config.ts:
Copy the browser-policy imports, constants and helper from a fresh single-page app starter if your configuration does not already define devBrowserHeaders. The check reads the configuration to help you test installed behavior; it does not verify served pages. Installed apps always enforce the browser policy, regardless of your local configuration. See local browser restrictions.
There is no environment variable for choosing the engine. ALTIMATE_ENGINE_URL is a different contract entirely — it is how the SDK’s for_local() runs your app process yourself, not a way to steer this command.
A frontend app has no server component of its own to hold a token, so dip app dev additionally runs a small local stand-in that your dev server talks to, so its requests behave the same locally as they do once deployed, without your browser ever holding an engine token directly. Against a dev cluster whose engine uses a self-signed certificate, set DIP_INSECURE_TLS=1. Like an installed app, your local preview page cannot get an engine token from /.altimate/token. Run queries through the preview’s built-in proxy at /.altimate/engine. When your app’s manifest declares a data capability, dip app dev waits for the data plane to pick up the app’s dev ceiling before your app starts, then tells you which state it is in. The wait usually takes a few seconds, and dip always answers within its 30-second request limit. A manifest with no data capability has no ceiling to wait for, so there is no wait and no message. Neither applies when you run a frontend app with ALTIMATE_DEV_APPGW pointing at an installed app: that run has no dev ceiling, and the installed app’s own access decides what it can read. the dev ceiling is active on the data plane means the data plane is enforcing your app’s ceiling, so a query inside it is no longer refused just because the ceiling hasn’t arrived. The query still needs everything else to hold: your own access, the table existing, the engine being up. the dev ceiling is still propagating to the data plane means the wait ran out: until the ceiling arrives, usually within a few more seconds, a query the ceiling allows can still be refused with PERMISSION_DENIED. dip doesn’t retry those queries, because a refusal while the ceiling is still arriving looks exactly like a real refusal. Run the query again once it has propagated. A query outside the ceiling is refused either way. For a python or streamlit app, dip app dev checks your python3 version before starting and stops with a remedy if it is below 3.10. It runs your app’s server process directly on your machine, so unlike dip app check it has no Docker fallback to fall back to. For every runtime except frontend, dip app dev also checks that its port is actually free before launching your app’s server process. If something else already has it (Docker, another dev server), it stops with port <N> is already in use on this host naming the port and dip app dev --port <free-port>, instead of your app’s own runtime crashing with a raw “Address already in use” error and no dip diagnosis anywhere on screen. This check is advisory, not a reservation: it releases the port immediately after confirming it is free. It is skipped for frontend, where vite decides its own port. For a frontend app, if the engine has scaled to zero, the app’s first query waits while the engine wakes, and dip prints dip: waking the engine, about a minute once instead of leaving the page silently loading. The query runs as soon as the engine is up; nothing needs retrying. Needs: a dip login session (not an API key), plus the toolchain your app’s runtime needs. For a python or streamlit app that means python3 3.10+ specifically, per the note above. Run dip app dev --help or dip app dev -h for a quick reminder of these flags: it prints the dip app command group’s summary (not this page) and exits successfully, without discovering an engine or starting a run.

dip app build

Runs docker build, baking your manifest into the image as an OCI label, and re-runs the conformance gate inside the build. The image runs as a non-root user. Needs: docker and a running daemon. Run dip app build --help or dip app build -h for a quick reminder of these flags: it prints the dip app command group’s summary (not this page) and exits successfully, without building anything.

dip app push

Default pushes show build phases, a heartbeat every 30 seconds, and a build/upload timing summary. The first push builds every layer from scratch (base image download, dependencies, conformance checks) and can take several minutes; later pushes reuse cached layers. Full build output is saved in a fresh dip-app-push-*.log file in your system temporary directory; the printed path remains available after the push. Use --verbose or DIP_VERBOSE=1 to stream raw build output instead.
Logs in to the plane registry, pushes a multi-platform image, then waits up to a minute for the registry to register the app’s version from its manifest label. Once registered, the app appears on the tenant’s Apps page. Run dip app install to confirm its access and code trust, then wait for a ready link to share. Members can publish and install their own static apps, built with dip app new --runtime frontend, by default. Publishing any other app needs a Data engineer. A version that is already published keeps the image it was published with. Before it builds, dip app push checks whether the manifest’s version is already in the registry and warns you if it is. After the push it looks up the registration of the exact image it pushed: With --json, a confirmed registration returns a structured receipt containing the app ID, version, image digest, registry, tenant URL, author and push event. Progress stays on stderr. Unconfirmed or unreadable registration exits nonzero in this mode. Without --json, the push-only outcomes and exit codes above remain available to existing CI jobs. Installation requires a confirmed receipt in either case and never infers success from the upload alone. Creating a new app requires permission to create apps; its authenticated user or service user owns the app. Registering later versions needs that owner’s credentials or permission to update all apps in the tenant. An explicit deny of App update also blocks the owner. An ownership refusal prints app <name> belongs to <owner>; ask them or an admin, or rename your app's id in the manifest and push again and exits with code 1. Increasing the version does not resolve this refusal. See App ownership. The look-up uses the same credential as the push, and needs apps:publish. With an API key, set DIPPR_URL (or pass --workspace) so dip knows which tenant to ask. dip only asks a tenant that lists the registry you pushed to, and only an answer for your authenticated user or service user, recorded after this push, counts. Another author’s push of the same image has its own outcome. If another dip login changes the signed-in user while the build runs, dip reports registration as unconfirmed. It does not use the replacement user’s publish history. A published version is compared by the platform images it runs, not by the digest of the image index around them. Each build writes a new provenance attestation into the index, so an unchanged rebuild has a new index digest. When its platform images are the same, it registers as the same version and the version points at the new index; installations keep running the same images. This applies to versions published after your tenant started recording each version’s platform images; a version published before that needs a new version for any repeat push with a new digest. If the rebuild produced different image layers, it is rejected even when the source did not change, so treat a repeat push of a published version as needing a new version. The pre-build check runs only for the default tag; a custom --tag skips it. Needs: docker, a running daemon, and the buildx plugin. Before it builds anything, dip app push checks that the build container can reach the registry. If it cannot, the push stops with one sentence saying what the build container saw and one thing to do, so a network or certificate problem costs seconds, not a full multi-platform build. When the registry name resolves to your own machine (a local development stack such as *.lvh.me), dip builds in a separate builder for that registry, named altimate-dip-local- followed by the registry name (for example altimate-dip-local-acme-registry-dev-lvh-me-8443-9efcaec1). It shares your machine’s network, goes to the registry directly even when you use an HTTP proxy, and trusts the certificate authority your machine already trusts for that registry. If your machine does not trust that registry’s certificate, the push stops before building and tells you how to trust it; dip never turns certificate checks off inside the build container. If the registry gives the build container no answer within two minutes, the push stops instead of building. dip pipeline push does the same. The registry login uses a temporary Docker configuration that is deleted when the push ends, so your key is never saved to ~/.docker/config.json or your keychain. See Where the key is stored. Run dip app push --help or dip app push -h for a quick reminder of these flags: it prints the dip app command group’s summary (not this page) and exits successfully, without pushing anything.
A multi-platform push builds the architecture your machine is not natively running under emulation. Docker Desktop ships that emulation; a plain Linux Docker install needs it set up separately (see docker/setup-qemu-action in CI, or docker run --privileged --rm tonistiigi/binfmt --install all locally). dip doctor cannot tell you whether it is available until after your first dip app push. See the emulation row in Install dip and sign in.

Which data plane it pushes to

A tenant can run several data planes, and each one has its own registry. An app can only be installed on the plane it was pushed to, which is why the success line always names the registry used. dip picks the target in this order:
  1. --registry / DIPPR_REGISTRY — whatever you name, taken as given. Also set --slug when the host does not already carry your tenant’s slug (a foreign registry such as ghcr.io).
  2. Several available registries with a named default: that default automatically, including on a terminal.
  3. Several registries without a named default: a numbered choice on a terminal. A headless run uses the first listed registry and announces the selection; use --registry HOST to choose explicitly.
  4. If no choice was made from the current plane list, the registry your session saved at login.
  5. Nothing cached and exactly one available plane: that plane’s registry.
  6. No saved registry: the registries your tenant publishes about itself, with its default preferred.
A tenant that publishes no registry at all fails here with an error naming the field it expected, never a guessed host.

dip app status

Read the current app’s installation once, with a 30-second deadline. Run this after installation instead of repeating dip app install as a check. It uses the directory’s saved publication receipt and, when present, saved installation ID. Missing receipts, another app’s receipt or a different login tenant or publisher are errors. Your existing human login authorizes the read. JSON includes the exact state, state_error, power_state, provision_succeeded, installation and app IDs, installed version and image digest, data plane and engine IDs, artifact generation, granted_capability_keys and ready. The access keys are what the read returned; an empty list alone does not prove the app has no access. Status never changes installation or consent. A successful read exits zero even when the installation is failed, stopped or still starting. ready is true only for an active installation whose runtime is ready and provisioning succeeded. Only then does app_url appear. This is deployment readiness, not proof that queries, charts or viewer permissions work. Open the URL in a signed-in browser to check the app’s behavior.

dip app install

Installs the exact app version confirmed by dip app push in this directory. Uses the publishing person’s dip login session, even when an environment API key is set. A key-only run is refused. An older or explicitly narrowed login without apps:install must sign in again and approve it. On a terminal, review the version, data access and code trust, then confirm. An agent first runs with --json, presents confirmation_required, selection, access and trust to the person, and asks for approval before using the returned confirmation value with --confirm. There is no automatic consent flag. OAuth login and existing data grants do not substitute for app consent. While it waits, progress goes to stderr in the console’s words for the installation, such as Installing or Starting, with the runtime’s state, such as (runtime ready), when the plane has reported one. Success prints the canonical app link on stdout, and on stderr who can open it and what it reads:
With --json, success is an object with state: ready, app_url, installation ID, exact installed version/image and explanation, the same sentences as a list. The text comes from the access the installation holds. If that differs from the access you approved, no link is printed and the error is stale_selection: installed access differs from the access you approved; running the command again submits your approved access again, replacing the other change. If the server cannot confirm the installed access before --timeout, no link is printed and the error is consent_unconfirmed. Starting installation or an unhealthy active app is not success. A failure returns the installation ID, state/error and retry command when an installation exists. Retry preserves the exact image, resumes one installation and checks current permission again. A new version or changed access needs a new confirmation. stale_selection asks you to review the changed publication; it never silently selects the newest app or different bytes. same_version_rebuild means the version you rebuilt is already installed from different bytes. An installed version keeps its bytes, so raise version in manifest.json, push, then install again. If your role’s own-app switch is off, a role administrator can select your role in Settings → Roles & permissions, then choose App installs → Manage own apps → Allow. Publication uses Data apps → Publish own apps → Allow. Wrong owner, scope, quota and unavailable-service refusals name their own remedies. See Install an app.

Pipelines

A pipeline is a dbt project that Dippr runs, schedules and reports on for you. dip pipeline scaffolds one, runs it on your machine as you, publishes it, and then runs and watches it on the platform. Pipelines are included in the standard tenant bundle (see Availability). In a tenant that does not include them, every command that reaches the workspace stops with “this workspace’s plan does not include the feature this needs”, followed by the workspace’s own answer, this tenant does not include the "pipelines" entitlement. No role or new sign-in changes that. Every dip pipeline command that changes something (push, register, run, cancel, pause, resume, set-engine, set-owner, delete) asks the workspace first, so it stops before it asks your browser for consent and before it builds or pushes an image. The one exception is a sign-in that lacks pipelines:read (one created before that scope was part of the default sign-in): the workspace refuses such a sign-in before it can say why, so the command may ask for consent first, and dip pipeline push then still stops before it builds or pushes an image. When dip can tell from your saved sign-in, or from DIPPR_API_KEY with DIPPR_URL set, that the workspace does not include pipelines, dip --help leaves dip pipeline out and dip pipeline new skips the agent skill. If dip cannot tell (you are signed out or offline), it shows everything as usual. Those commands and list give a different answer when the workspace’s server does not offer pipelines at all (the service is not deployed there): they stop with pipelines are not available in this workspace and exit 1. That is not the plan message above, which means the service is there and the plan lacks it. They check before requesting browser consent, building or pushing an image, including when an older sign-in lacks pipelines:read. The message adds that no new sign-in or API key will add pipelines, so there is nothing to retry. dip pipeline list, runs and events on a sign-in that lacks pipelines:read stop with a message that prints the command to run, dip login followed by your workspace address. It also says that dip could not check whether the workspace has pipelines, because that check needs the same permission. On a workspace that runs an older server, such a sign-in can get this message even though pipelines are not deployed there, and the new sign-in is then told so. If the address names a tenant that does not exist, pipeline commands, including push --re-register, instead report unknown workspace. Check --workspace or DIPPR_URL for a typo or an address that is no longer in use. A pipeline names the Trino catalog and schema its models build into, in pipeline.py: dbt_project(..., catalog="lake", schema="finance"). dip pipeline new --catalog lake --schema finance writes them for you. A dip pipeline dev run without both stops before dbt starts and says which one is missing. Each value is a plain name: letters, digits and underscores, not starting with a digit. A pipeline whose dbt commands include run-operation names the macro that command calls, and its arguments, in pipeline.py:
The macro is a dbt macro name, or package.macro for a macro from a package. The arguments are names and text values, passed to dbt as --args. A run then calls dbt run-operation grant_select --args '{"role":"reporter"}', locally and on the platform alike. dip pipeline check and dip pipeline push refuse a pipeline that declares run-operation without an operation, an operation without run-operation, and an argument whose name looks like a secret. dip pipeline build and dip pipeline push refuse that secret-looking argument name before Docker starts.
Every command above that takes a pipeline accepts its id (finance-marts) or its display name ("Finance Marts", the name the console shows; dip pipeline list shows both). An id is tried first, so an id always means that pipeline, even when another pipeline’s display name is the same text. Otherwise the name must match exactly, including case, and dip says which id it resolved the name to. When two pipelines have that display name, the command is refused, lists their ids, and sends nothing: pass the id instead. With --json that refusal has class refused and lists the ids in existing_ids. A name nothing has is refused too (not_found), with any name that differs only in case offered as a suggestion. delete resolves a name the same way and still needs --yes. Finding a name needs permission to read pipelines; a role that may run, pause or delete a pipeline without reading it can still act on it by id. Every command above that takes a pipeline takes exactly one (events takes the pipeline and the run id). Flags and their values can come before or after it: dip pipeline run --select orders_daily finance-dbt runs finance-dbt. Each command accepts only the flags in its synopsis above (the write commands also take --workspace, --no-browser and --browser-wait; runs and events take --workspace). Flags take two dashes. A second id, a flag the command does not take, a flag given twice (--yes and --no-yes count as the same flag), a one-dash spelling such as -limit, or a flag with no value after it (at the end, or followed by another flag) is refused and nothing is sent. A yes-or-no flag takes true or false (--yes=true, --json false); its --no- form, such as --no-browser, takes no value. To address a pipeline whose id starts with -, or is true or false, put it after --; nothing after -- is read as a flag: dip pipeline runs --json -- -legacy.

Publishing a new version

Each dip pipeline push publishes the version in pipeline.py, and a published version never changes. To publish a change, raise version and push again. push regenerates pipeline.json from pipeline.py before it reads the version, so you do not need to regenerate it yourself. Without python3, push publishes the version already written in pipeline.json and tells you it did not regenerate it. Before it builds, dip asks your tenant what publishing this pipeline.json and this dbt project would do. The dbt project is compared as the image build would copy it, together with dbtDockerfile itself, so a file your .dockerignore (or dbtDockerfile.dockerignore) leaves out, such as target/ or profiles.yml, does not count as a change. If dip cannot read a file the build would copy, it stops before it builds. When the pipeline project is its own repository root, exclude .git in the ignore file the build uses: dbtDockerfile.dockerignore if the project has one, otherwise .dockerignore. Otherwise the build copies .git, and every commit changes the project as dip compares it. Your tenant makes that decision, and nothing is saved by asking, so it needs no permission beyond the API key push already uses. If dip cannot get an answer (for example, a temporary server error or a tenant that does not support the version check yet), it says so, builds and pushes, and the platform still refuses a version it cannot take without changing the registered pipeline. Only the current version can be sent again: an older published version is refused, and nothing changes. If the workspace instead reports that pipelines are unavailable, dip stops without building or pushing. dip pipeline push --re-register sends the current version again without building or pushing anything. It reads the pipeline declaration and dbt manifest from the image that version registered, and sends them unchanged, so the pipeline itself does not change, and asks Dippr to send its table lineage again. That lineage step is best effort: the command succeeds whether or not the lineage arrives, and it does not tell you which happened. Use it when a pipeline’s lineage is missing or out of date after a publish, and if the lineage is still missing afterwards, run it again later. It needs the same credential as push, plus pipelines:read, and it stops without sending anything when:
  • the pipeline is not published, or pipeline.py declares a version other than the published one;
  • pipeline.json here differs from what was published (publish that as a new version instead);
  • the published image is not on a registry your tenant names (one it lists as its registries, or one of your data planes’ registries), or --registry names a different registry. A registry you passed to dip login --registry does not count unless you pass it to this command too. A pipeline pushed with --tag to another registry, such as GitHub or ECR, cannot be sent again this way: dip reads the image with your Dippr API key and never sends that key to another registry. Publish a new version instead.

Credentials for pipeline commands

push and register work with a dip login sign-in or with a service user’s API key. In CI, set DIPPR_API_KEY. When your sign-in does not yet allow publishing, dip opens your browser once to ask for pipelines:publish (and apps:publish for push) before it builds or pushes anything, and changes nothing if you decline. Either credential needs: With --no-browser and no key, dip stops before it builds or pushes anything and names the permission your sign-in is missing. run, cancel, set-owner, pause, resume and delete need pipelines:manage, which dip login does not ask for. The first time you run one of them, dip opens your browser once to ask for that one permission, added to the ones your sign-in already has. It asks before anything changes, so a declined request costs you nothing. In CI, set DIPPR_API_KEY to an API key that has the permission instead. The pipeline commands take the pipeline’s id, the first column of dip pipeline list (such as finance-marts), or its display name, the name= column. Secrets are read from standard input only. For the API key scopes these commands need, see Scopes and consent. Attach an owner by piping its key, so the key never appears on the command line:

Pipeline JSON output

dip pipeline list --json and dip pipeline runs --json print a JSON array, and [] when there is nothing to list. dip pipeline run --json prints the run it started as one object with the same keys and value formats as a row of dip pipeline runs --json. It shows the run as it was when it started, usually queued; a later dip pipeline runs shows its current state, counts and finish time. dip pipeline cancel --json prints the cancelled run the same way, with state cancelled. Every object carries every key, even when its value is empty or zero. Keys are snake_case, states are lower-case words, and times are RFC 3339 strings ("" when unset). Any of kind, mode, last_run_state, state and trigger whose value this version of dip does not recognize (one a newer Dippr release added) is unknown, never a number. The value lists below are the ones this release of dip knows. dbt always verifies the engine’s TLS certificate, both in dip pipeline dev and on the platform. By default it trusts the same certificate authorities your Python does: SSL_CERT_FILE if you set it, otherwise certifi’s bundle. If your engine’s certificate is signed by a private or development CA, set ALTIMATE_ENGINE_CA_BUNDLE to that CA’s PEM file. No setting turns verification off, and a path that is not a file stops the run rather than being ignored.

Data planes

dip plane list

Lists every data plane with its tenant-specific and shared OAuth-only MCP endpoints, plus the registry dip app push would use for it, and the release each plane last reported with its support verdict (a version line; in --json, chart_version, contract_version, version_status, version_message and upgrade_by). See Plane versions. On a plane you own, each failure the plane reported in the last 24 hours adds an errors line (in --json, recent_errors; recent_errors_withheld is true on another tenant’s plane that reported some). See Recent errors. The default plane is listed first. Walked to the last page, so the answer is always the whole set. Each plane also shows its declared outbound IPs on an egress line (egress_cidrs and operator in --json). A BYOC plane that declared none reads none declared: once plane connections are restricted to declared addresses, its connections are refused unless they leave from an address your deployment admits anyway (one another plane declared, or the deployment’s own list). On a plane your tenant joined but does not own, the addresses are the owner’s to see: the line reads set by the plane's owner, and --json reports egress_cidrs_withheld: true with an empty list. See Outbound IPs. A runs line says where the plane runs (reachability in --json): with the control plane (same cluster) (in_cluster), remote (connects over the internet) (remote), or not recorded (unknown) for a plane registered before Dippr asked, which is treated as remote. A managed plane recorded as remote that declared no outbound IPs gets the same none declared warning as a BYOC plane. See Where a plane runs. A temporal line says whether your deployment restricts plane connections to declared addresses (temporal_egress_enforcement in --json: enforce, open, or empty when every plane runs next to Dippr’s own services). On a restricted deployment, a plane outside the control plane’s cluster (any BYOC plane, or a managed plane recorded as remote) that declared no outbound IPs reads no egress CIDRs declared, and the cell enforces its Temporal allowlist (temporal_egress_undeclared: true): its connections are refused unless they leave from an address another plane or the deployment’s own list declared, so its owner should declare them. The flag names the missing declaration; dip cannot see the shared list, so it does not say whether the plane connects. See When plane connections are restricted. Needs: a signed-in session or an API key.

dip plane prove

Binds this tenant to a data plane by proving you hold that plane’s private key, rather than through an ordinary invite. This exists for an operator running a plane with no control-plane account of its own to invite from — the key is the only consent signal available in that case, and the plane’s owner has to have opted into accepting it first.
There is deliberately no flag that takes the plane’s private key value directly — only a file path or stdin, or the DATAPLANE_PRIVATE_KEY environment variable, because a secret on the command line is visible to every process on the machine and lands in shell history. --key-file wins when both are set.
The plane’s own private key never leaves your machine: dip answers a one-time challenge with a cryptographic proof derived from it, and only that proof crosses the network. Needs: a signed-in session or an API key.

dip plane support-bundle

Collects one .tar.gz file about a data plane running in your own cluster, for you to send to support. It runs kubectl and helm on your machine with your current kube context (or --context), so it needs cluster read access but no sign-in. The bundle holds: Secrets are redacted before anything is written:
  • Secret values are never written, and a value a Secret in the namespace holds is replaced by [REDACTED-SECRET-VALUE] wherever else it appears, for example in a log line or an env var. A short value under a key that is not named like a secret (a port, a flag, a short word) is left alone, because replacing it everywhere would erase names the logs need; manifest.json then records "short_values_not_value_redacted": true, and the name and shape rules below still apply.
  • A value or env var whose name contains pass, pwd, secret, token, credential, auth, cookie or signature, or ends in key, is replaced by [REDACTED].
  • A name/value record (for example name=DB_PASSWORD value=… in a log line, or a printed struct) whose name looks like a secret has its value replaced, whatever the order of the fields. On a line that names such a secret, every value on the line is replaced up to the end of the line, and on into the next lines while a quote or bracket it opened is still open (at most 64 lines), because a value printed without quotes has no reliable end. Other text on that line is removed with it. When a value printed without quotes holds a bracket of its own (for example Value:first then second}OK on the next line), the bundle cannot tell where the record ends and removes up to 64 more lines rather than risk keeping part of the secret.
  • Anything shaped like a plane credential (alt_plane_…), another alt_ key, a registry robot account’s secret, a private key, a bearer or basic authorization value, a JWT, or a password in a URL is replaced by [REDACTED].
  • A listing that cannot be read as expected is left out and recorded in manifest.json instead of being written unredacted.
If your access does not let you list the namespace’s Secrets, the bundle is still written, the command prints a warning, and manifest.json records "value_redaction": false: only the name and shape rules applied.
Open the bundle and read it before you send it. Redaction removes credentials by name and shape, but your logs can still hold hostnames, database names and other details about your environment.
Needs: kubectl and helm on your PATH, with read access to the plane’s namespace.

dip plane keygen

Generates the keypair for a data plane you run in your own cluster (BYOC). The private key is written to one place you choose and is never printed or sent: a new file created with mode 0600, or a new Secret in your cluster (key private-key). An existing file or Secret is never overwritten. The public key is printed on stdout; it is what Settings → Data planes → Register asks for. Most people use dip plane install instead, which runs this step for you. Needs: kubectl on your PATH for --secret. No sign-in.

dip plane install

Installs a data plane into the cluster your kubectl points at, in one command. It generates the plane’s keypair on your machine, registers the plane with your tenant (operated by you, reachable remotely, with your outbound IPs), writes the plane credential and the image pull credential straight into Secrets in your cluster, and runs helm upgrade --install from the published chart, pinned by digest. Before it pulls the chart or registers anything, it checks with cosign that the chart is signed by Dippr’s release (https://github.com/AltimateAI/altimate-adp/.github/workflows/release-chart.yml@refs/heads/main, issuer https://token.actions.githubusercontent.com), and stops with nothing changed if it is not. No credential is ever printed. See Install a data plane in your cluster for the full walkthrough and what your values file must contain. Running it again is safe. Progress is kept in the ConfigMap altimate-plane-install in the plane’s namespace, a plane is never registered twice, and a run that stops part way says what exists and resumes when you run the same command again. Running it later with a newer --chart, and global.imageTag in your values file set to that release’s tag, upgrades the plane: every plane image is pulled at global.imageTag, so a new chart with the old tag runs the old images. Needs data_planes:administer (“Bring data planes into your tenant”), which no default sign-in carries, and a role allowed to register data planes, such as data_admin. Either set DIPPR_API_KEY to an API key minted with that scope, or run it signed in with dip login: the first time, dip opens your browser once to add that one scope to your sign-in, and registers nothing until you approve it. Also needs kubectl, helm and cosign v3.1.3 or newer (an older cosign is refused before it is asked anything) on your PATH and an admin role on both the plane’s namespace and the apps namespace.

Query engines

dip engine list

Lists every query engine you may see: its name (what dip app dev --engine takes), kind, URL, power state, and the state of its last catalog sync. The complete catalog list for an engine, and which integration each catalog maps to, is available only in the console. Open the Query engines page for that. In --json, read_status is complete, partial or failed. If no tenant’s inventory can be read, the command exits non-zero and keeps the failure details, including any request ID, in warnings. A partial read keeps the available rows, exits 0 and labels the inventory incomplete. Only a complete empty read prints no query engines listed. and exits 0. A warning about optional metadata crawl status does not make the engine inventory incomplete. Resolve the reported access or connection problem before treating missing rows as absent engines or creating another engine. The row can also carry last_sync_error, a plane-supplied message, in --json and as a labelled line under the engine in the text report. Read the label, not only whether the field is present:
  • When the last sync landed on error, it is a genuine failure and prints as sync error .... A catalog-apply failure names the failing catalog inside the text, so a catalog name can appear here even though the complete catalog list stays console only. A provisioning failure (a problem with the engine itself, not a catalog) does not name one, so read the message rather than assuming a catalog name is always in it.
  • An engine can carry a non-empty last_sync_error while last_sync_status is still synced or pending. This happens when a check-only sweep could not re-verify one source’s fingerprint; the engine’s catalog set is unaffected, so it prints as sync note ..., not sync error. The engine stays usable and no apply is needed to clear it, but the reported source-access problem, such as a missing object, a rejected credential, or an unreachable connector, is real and worth investigating before it becomes an actual sync failure.
Either way this is otherwise readable only as a hover tooltip on the console’s SYNC FAILED badge. An engine with neither omits the field. The same field, labelled the same way, is on the row dip engine create, dip engine config and dip engine apply print back. last_sync_status: synced says the catalog set was applied, not that every source behind it answers. When the metadata crawl status can be read, each row also carries failed_catalog_count and failed_catalogs: the catalogs the last crawl could not read, each as the catalog name, a colon and the reason, usually a broken host or a rejected credential on the source (dip integration test <source> says which). Deleted sources awaiting catalog apply do not count as failures. Reading it needs query_engines:write; a read-only login or key skips it silently and the fields are absent. They are also absent, with a warning, when the crawl status could not be read, so an absent count never means zero. Needs: a signed-in session or an API key.

dip engine create

Registers an engine and dispatches its first catalog sync. Provisioning is asynchronous — the engine has no client-facing URL until it is up. By default this also turns on search indexing for the engine’s data plane, so search finds the new catalogs without a second step. It applies only to a plane you have not configured yet, so it never overrides a plane you have turned off or pointed at a specific engine. Enabling indexing costs engine time (and embedding spend, if configured); pass --no-index to skip it. Run dip crawl status to see the crawl. If your plan does not include metadata search, the engine is still created and indexing is simply left off. On a data plane Dippr runs, a workspace’s first engine also gets the sample dataset, added as you. If your role doesn’t include workspace databases, the API key or token you used lacks workspace_db:write, or your permissions can’t be checked at that moment, the engine is still created without it and the output ends with one line saying why and what to do next. --json carries the same sentence as sample_dataset_note, which is absent otherwise. Needs: a signed-in session or an API key, with the write capability the capability table below covers. With --wait, it also needs query_engines:list, which it needs to poll the new engine after creating it. A credential missing that capability is refused before the engine is created.

dip engine config

Changes an engine’s tunables. This only stages the change — the engine keeps running its current configuration and nothing restarts until you run dip engine apply. Because the configuration is a full replacement on the wire, dip reads the stored configuration first and merges your --set/--clear onto it before sending it back, so --set warehouse=bigger_wh changes only that one key rather than reverting everything else you did not mention.

Sizing an engine

--set size=m is the normal way to size an engine: one rung of a fixed ladder that the platform expands into workers, memory and CPU limits for you. Which rungs you may pick depends on your tenant’s plan; a size your plan does not include is refused, naming the size and listing the ones your plan has. The individual knobs (workers, coordinator_heap, worker_heap, coordinator_cpu, worker_cpu, query_max_memory, query_max_memory_per_node) need --set size=custom to change by hand — on any other size they are owned by the rung, and a value that contradicts what the rung derives is refused rather than silently overwritten. spill_enabled and workers_spot are settable at every size. There is no “attach a catalog” command, because an engine’s catalog set is derived from your tenant’s integrations that have the federation capability on that engine’s plane. To attach one, run dip integration create --capability federation, then dip engine apply. Needs: a signed-in session or an API key, with query_engines:write.

dip engine apply

Materializes every staged configuration change and any newly federated catalog. When that changes what the engine runs, this restarts the engine and fails every query currently running on it, including other people’s. That is what --yes is for. dip cannot tell beforehand whether a given apply restarts the engine, so its progress line says “if this changes what the engine runs” rather than promising a restart. It also nudges a metadata crawl on a best-effort basis, so the search index usually catches up without a separate dip crawl start; run dip crawl status afterward if you need to be sure it actually did. If an apply is already running on the engine, this one is handed to it and runs as soon as it finishes, with a fresh read of your data sources. dip then says it joined the running apply, and --json reports "dispatched": true, "joined": true. "dispatched": false still means nothing was started or queued (see catalogs and apply). Needs: a signed-in session or an API key, with query_engines:write.

Waiting for create and apply

--wait on dip engine create and dip engine apply turns the command from “dispatched” into “here is what actually happened”, at the cost of the command staying open until it has an answer. On apply, dip checks the engine’s sync state right before applying anything. If the engine is already syncing from something else at that moment, dip waits for that to settle first. The platform gives no per-apply id, so applying on top of an in-progress sync would leave no way to tell the two apart afterward. Only once the engine is confirmed idle does dip apply and start watching: it does not treat the engine’s sync state as done only because it reads synced, since the engine could be sitting at synced from that earlier sync the instant this apply dispatches. It confirms the sync state actually moved (a syncing reading, or the sync time or error changing) before it will accept a later synced reading as this apply’s own outcome. For a running engine the sync reads synced only once the engine the apply restarted is serving the new catalogs (a stopped engine reads synced once they are written, and loads them when it next starts), and dip also waits for the engine to read ready (or stopped) before it reports success. If the engine is still not serving them after a few minutes, the sync reads error with a reason saying the catalogs were written and the engine is still restarting. Run dip engine apply again once the engine is up to record synced. (A different apply someone else triggers at that exact same instant is one case dip cannot rule out; the platform gives it no way to.) A post-dispatch error reading is deliberately never reported as exit 1, for either verb. The tenant also runs a periodic background sync: for apply, that sync dispatches a read-only check against every engine, and a failed check writes the identical error text and leaves the sync timestamp unchanged, the same shape a failed apply produces. For create, the SAME background sync dispatches a standalone catalog sync for every engine on every tick, including one your create is still provisioning, and a failure there also writes the identical reading a failed first sync would. With no per-operation id on the wire, dip cannot tell either verb’s own failure apart from that unrelated, concurrent sync failing at the same moment, so it reports that combination as inconclusive (exit 3) rather than guessing. Exit 3 is not a failure of the engine or the apply. It means dip could not confirm the outcome in the time it watched, could not attribute an error reading to this operation specifically, or lost the ability to keep checking. Nothing is cancelled: the operation keeps running on its own, and dip engine list reports the real outcome whenever it lands.

dip engine delete

Destroys the engine. Everything pointed at it (data apps, MCP clients, anything holding its URL) stops working. Its catalogs are derived from your integrations and are not themselves lost. Refuses without --yes. Before deleting, dip lists your pipelines and names the ones whose runs are pinned to this engine, in the refusal without --yes and as a warning on stderr with it. The workspace refuses to delete an engine that a pipeline is pinned to, and the refusal names those pipelines: re-pin each with dip pipeline set-engine <id> --engine <name or id>, then delete again. With --json, a refused delete prints the error document, with the refusal (and the pipeline names) in its message. A successful delete’s report lists pinned_pipelines only when a pinned engine was deleted anyway. That happens against a workspace that does not check pins yet, or when a pipeline is re-pinned between dip’s check and the delete. Separately, if dip cannot read your pipelines (your credential lacks pipelines:read, or the read was refused), it says so in the confirmation, on stderr and as pin_check_warning, rather than reporting that none are pinned. The workspace still checks pins itself. Needs: a signed-in session or an API key, with query_engines:write. The pinned-pipeline check also uses pipelines:read, which an ordinary dip login grants.

Connected data sources

dip integration list

Lists every connected data source you may see: name, kind, the data plane running its connector, and its capabilities (driver, federation, mcp, cloud_auth). This is what is registered, not what is reachable — there is no health field here, and no listing dials anything. Stored credentials are never readable through this or any CLI read; they are write-only and always read back as a placeholder. Needs: a signed-in session or an API key.

dip integration create

Registers a data source. This creates a record; it does not verify anything — run dip integration test afterward to find out whether the platform can actually reach it. Integration rows include credential_status: not_required, missing, stored, or rejected. rejected is reported only for PostgreSQL, ClickHouse and Redshift, whose connectors say when a database refused the login; any other kind with a stored credential reads stored, even after a refused login. When dip integration create --json saves a source without a needed credential, next_steps lists how to enter it through --secret-stdin, open the source’s console page, or invite its holder with dip member invite <email> --role data_engineer. Under --json, the response carries a pending_engine_apply boolean alongside action and integration. It is true for a source registered with federation (or a newer capability this version of dip does not recognize yet): the record exists, but no engine renders it until you run dip engine apply <name|id> --yes on every engine that should mount it. The human-readable note says the same thing, but that note is not part of the JSON document, so a script parsing --json needs this field to know an apply is still owed. Omit --capability to use the kind’s required capabilities. For example, a postgres source gets driver. To also enable federation, pass both --capability driver --capability federation. When you name capabilities explicitly, you must include every capability the kind requires; missing or unsupported capabilities are refused.
There is deliberately no --secret key=value flag. A secret on the command line is visible to every process on the machine via ps and lands in shell history — this is why --secret-stdin exists at all. Which keys a kind’s secrets use is documented per connector kind in the bundled altimate-connect skill (dip skill install).
Needs: a signed-in session or an API key, with integrations:write.

dip integration update

Changes a registered source. Configuration is a full replacement on the wire, so dip reads the stored record first and sends your --set/--clear values merged onto it — a secret you do not mention is preserved, and --clear KEY removes a config key or a secret. --capability is also a full replacement, but unlike config there is no read-then-merge: the set you name is the complete new set of what the platform may do with this source, not an addition to what is stored. Omit the flag and the stored capabilities are left alone. dip checks that the capability change actually landed. If the record the workspace sends back does not carry exactly the set you named, the command fails instead of printing updated, with class old_server under --json. The workspace is most likely older than your dip, and the error tells two cases apart:
  • Ignored. The returned set is the one stored before. The workspace does not read capabilities on update, so nothing about them changed.
  • Partially applied. The returned set differs from both the one you named and the one stored before. The workspace replaced the set but dropped a capability it does not recognise, so a capability you left out (say federation) was removed even though one you named was not added.
In the partially applied case, or when the same command also renamed the record or changed its config or secrets, something did land and the error says so (may_have_landed: true). Check with dip integration list before re-running. If the record carries federation, cloud_auth or tunnel, the error also names the dip engine apply step, because running engines keep the previous rendering until one is applied. A value-taking flag with no value is refused before anything is sent, because the flag would otherwise be silently ignored. This covers a flag left as the last argument (dip integration update warehouse --capability), a flag immediately followed by another flag (--workspace --json reads --json as the workspace value), and an empty routing value that would fall back to the default target (--workspace/--plane, and --mcp-resource for the dip db verbs). To pass a value that itself begins with -, use the --flag=value form. The dip integration, dip engine, dip ontology, dip semantic record write verbs and the dip db write verbs enforce this (dip db exec through its own value-flag validation). In dip db sql, the argument after --sql, --file, --max-rows, --plane, --workspace or --browser-wait is always that flag’s value, even when it begins with -, so --sql --json is not also read as --json. The one exception is -h / --help: it is a help request wherever it appears, so dip db sql --file --help prints help. Dropping a capability this way is a normal CLI write, but the server still enforces the kind’s own required capabilities and refuses an update that omits one. A postgres integration’s driver or an iceberg integration’s federation, for example, cannot be dropped, no matter what set is named. So this is the CLI way to stop a source from being federated onto an engine (or exposed over MCP, or used for driver connections) without deleting the record, only for a kind where that capability is optional: dip integration update <name> --capability driver drops every capability but driver for a postgres source (federation and mcp are both optional there), and fails outright for an iceberg source, whose federation is required. The refusal names the missing capability, so you find out before anything changes, not after. When the one you need to drop is required, deleting the integration is the only way.
Dropping federation here only changes what this source is now ALLOWED to be. It does not touch what any already-running query engine is currently serving. An engine keeps rendering the catalogs it had at its last dip engine apply; this update marks that set out of date but leaves it running as-is. The source stays queryable from every engine that already mounted it until you run dip engine apply on each of them. That command restarts the engine, failing every query in flight, including other people’s. Treat dropping federation on a source you believe is broken or untrusted as two steps, not one: the capability update, then dip engine apply <name|id> --yes for every engine that had mounted the source. apply targets one named engine, so applying only one leaves the source queryable from the rest. There is no CLI listing of which engines mount a given source today, so when in doubt apply every engine on the source’s data plane.
There is no way to clear every capability down to none through this flag: the wire reads an empty list as “unchanged,” the same limitation --clear runs into on a config’s last remaining key. To remove every capability, delete the integration instead. Under --json, the response carries a pending_engine_apply boolean. For a source that carries federation (either before or after this update), it is true whenever the update actually changed something, name, config, secret or capability, since a directly-mounted source’s name is itself part of what an engine renders. For a source that carries only cloud_auth or tunnel, it is true only when the update changed config, a secret or a capability; a rename-only edit stays false, because such a record is never mounted on an engine directly and a rename changes nothing the integrations that reference it render. Read this field rather than the prose note when scripting: the note is not part of the JSON document.
This is a read-then-write with no concurrency check: if someone edits the same integration in the console between your read and your write, their change is silently overwritten with no conflict and no warning. Read the record back after writing it, and re-run dip integration test whenever the change touched a credential — an update stores invalid credentials exactly as readily as valid ones.
Needs: a signed-in session or an API key, with integrations:write.

dip integration test

Dials the external system with its stored credentials and waits for the answer — up to about 25 seconds, since it is a real round trip to a real warehouse. A failed probe exits non-zero. On the wire, a failed connection is a normal answer rather than a fault (invalid credentials are an answer, not an error), so this command’s exit status is a deliberate choice: reading stdout to learn whether the answer was “no” is not something a script should have to do. With --json, a failed test includes credential_status and the source’s text in reported. A missing credential adds likely_cause: "no_credential_stored" and next_steps for entering it or inviting its holder. A rejected status means the source refused the stored credentials (reported for PostgreSQL, ClickHouse and Redshift only). Needs: a signed-in session or an API key, with integrations:write.

dip integration delete

Destroys the record and its stored credentials. Refuses without --yes. Under --json, the response carries a pending_engine_apply boolean. It is true when the deleted source carried federation (or a newer capability this version of dip does not recognize yet): every engine that had mounted it keeps serving its catalog until you run dip engine apply <name|id> --yes on each one. A cloud_auth or tunnel record reports false, because the delete itself refuses while anything still references it, so a successful delete proves nothing was relying on it. Needs: a signed-in session or an API key, with integrations:write.

dip integration sample

Adds the sample dataset (historical US avocado prices) to your tenant and makes it queryable. It is the same action as Use sample data on the console’s Overview page, followed by the steps that make it answer a query:
  1. Adds the sample as a read-only catalog.
  2. Waits for Dippr to apply your engine’s catalogs, which restarts the engine. Dippr does this on its own when the restart affects nobody else (the automatic apply). If it does not, the command stops and prints why; --yes restarts the engine anyway, which stops the queries running on it.
  3. Waits until the engine reports the new catalog set as synced, or reports the sync error and exits non-zero.
  4. Prints the catalog name the engine serves and a first query to run, for example SELECT * FROM "avocado_prices_sample"."main"."avocado_prices" LIMIT 5.
If your tenant has no engine yet, it only adds the sample and tells you so; the first engine you create picks it up. Running it again is safe: the existing sample is reused. If the wait times out after an apply was dispatched, the result is inconclusive (exit 3). Check dip engine list before retrying; the sample may already be available. A signed-in session that needs additional consent opens the browser after you confirm the engine restart with --yes. The catalog name comes from the engine itself through MCP browse with level=catalogs; the first query uses browse with level=tables and the catalog name, without a schema, to find a table. An API key with query_engines:execute_sql reads it directly. With a signed-in session, dip gets a token for that data plane from your login, with no browser. If your workspace cannot issue one yet, it uses the token from dip mcp login if you ran it; without either, the sample is still added and applied, the catalog is left empty, and a warning says what to run. Needs: workspace_db:write to add the sample and query_engines:write to apply it. A dip login carries workspace_db:write; a session from an older dip, or one narrowed with --scope, opens your browser once to grant it. An API key must be minted with both, plus query_engines:list, and query_engines:execute_sql for the catalog name.

Documents

dip doc upload

Adds a local file as the person signed in with dip login, into a folder they may add to. Documents must be enabled for the tenant. API keys cannot upload. Older logins may open a browser for documents:write and separate documents:share_uploads consent; --no-browser refuses when either approval is missing. Existing uploader-only grants remain private until sharing is separately approved; older clients retain private uploads. Identical-upload reuse requires an updated Dippr CLI. Older CLI versions continue to add a new copy when the same file is uploaded again. By default, adding identical bytes to the same folder reuses your own indexed file if you can still read it, even if you rename the file. The result is unchanged with the existing document ID; its sharing and classification stay unchanged. Another person’s file is never reused. On tenants using Documents access, a tenant admin can turn off Reuse identical files added by agents for the selected Data plane for agent uploads under Settings > Documents access. Changed bytes create a separate document. If you already have a readable file with the same name in that folder, the upload says “An older document with that name exists in this folder.” This name check is case-sensitive and also applies when reuse is off. Console uploads and Replace keep their existing behavior. Simultaneous uploads can still create duplicates before either file finishes indexing. Capacity checks happen before reuse, so even an identical retry can be refused when Documents is full. Agent uploads use your default classification for the folder. On tenants using Documents access to manage folder permissions, with sharing approved, sharing is queued by default for people the folder-access policy identifies as readers at admission, then checked again before publication. Later readers do not automatically gain access. The policy projection must have been successfully fetched within 60 seconds; permission changes may take longer to appear. A tenant admin using this setup can turn this off under Settings > Documents access. Select the Data plane for agent uploads first: these preferences apply only to that plane. Review each plane separately, including planes selected by dip doc upload --plane. Folder access grants apply across the tenant. New agent uploads on the selected plane are then shared only with you while you retain folder and classification access. Existing files are unchanged. On the earlier, support-managed Documents setup, new agent uploads stay private to you while you retain folder and classification access, even with sharing approved. The upload returns a note explaining that automatic sharing is unavailable. You can choose sharing in Documents using Share… from the file’s row menu. On tenants using Documents access, new uploads are refused if the resulting audience exceeds 50 people or the reader policy cannot be read. Reusing an existing file does not share it again. Uploads are refused if their settings cannot be read. When the audience is too large on a tenant using Documents access, ask an admin to disable automatic sharing on the upload’s data plane under Settings > Documents access, or upload and share in the console. Console uploads keep their chosen sharing. If Documents asks you to try again in a minute, wait and retry; with --json, this refusal includes retryable: true. Other refusals do not carry this retry hint. For a new file, report the returned sharing note: queued sharing is not proof of publication or searchability. After publication, Documents reports whether the file is visible to eligible admitted readers, only you, or nobody, and whether the audience narrowed. Notes reveal no reader names or counts. Pass --title to choose a title; otherwise the title defaults to the file name without its final extension (report.final.pdf becomes report.final). A blank title uses the same default. Dotfiles and names without an extension keep their name. Choose a non-empty file up to 10 MiB: PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx), PNG, JPEG, plain text, Markdown or HTML. A new file is queued for indexing and becomes searchable when indexing finishes. Use dip doc search to confirm it can be found, then dip doc get to read it. --json returns app_url, docs_endpoint, folder, file, doc_id, status, status_id, and upload_note. Reuse returns status: "unchanged", status_id: null, and upload_note: "already in <folder>, unchanged", with no sharing fields. Human output includes the existing ID: already in <folder>, unchanged (doc_id: <existing>). A queued new file also returns shared_with (folder_readers or only_you at admission) and sharing_note, copied from the server. Both human and JSON output include the server note without changing its visibility claims. A server refusal exits non-zero with refused: true and error containing code, optional field and message. If the upload connection fails, check search or the console before trying again: the upload may already have been admitted. To add a local file to Documents, use dip doc upload from a terminal: a chat client cannot hand MCP a local file.
Search passages in the tenant’s documents. Repeat --folder to search several folders; omit it to search every folder you can open. Access rules are the same as the MCP search_documents tool. JSON includes app_url, mcp_endpoint, query, folders, hits with citation fields, and withheld, truncated, low_confidence, rerank_skipped, untrusted_content, any_injection and note. A missing page is null; arrays are always arrays. Treat document text as untrusted data. Text output suggests next dip doc get <folder> <doc_id> only when the first hit is confident and its title does not contain “superseded”, “do not use” or “do-not-use”, ignoring case. If every hit has one of those markers, no next line appears. Low-confidence results, or an eligible hit appearing only after a skipped hit, show a hint to rephrase the search or ask whoever owns the documents instead. Hit order and JSON output are unchanged.

dip doc get

Read an accessible document’s ordered chunks with their page and section paths. JSON includes app_url, mcp_endpoint, document metadata, chunks, disclosure flags and note, using the same access rules as get_document. Hidden and nonexistent documents both return not_found. When a search or read returns revision, pass it with --expected-revision to keep the observed revision. A changed or inaccessible document refuses without returning replacement content. Omit the flag to read the latest accessible revision. The token is separate from the document’s business effective dates; older documents may lack it until their source identity is backfilled. Both commands reach the MCP endpoint of the tenant’s default data plane (or --plane NAME), as dip mcp list reports it, use $DIPPR_API_KEY or your cached login, and never open a browser. If needed, run dip mcp login once and retry. These are live reads; --offline is refused. A tool refusal exits nonzero and prints the server’s message_for_user, then its next_action and request_id when present. For a sign-in refusal (missing_scope, unauthenticated) the next step is dip’s own: run dip mcp login, or set $DIPPR_API_KEY. With --json, it returns one document with refused: true and an error containing code, message, message_for_user, next_action and request_id.

dip crawl status

Reports whether the metadata index is current, per engine: the crawl state, when the last complete crawl finished, how many documents are served, which catalogs the last crawl could not read, and whether search indexing is switched on for the engine’s data plane (indexing in --json: enabled, disabled, or empty when the workspace did not report it). When indexing is off for a plane, no crawl can run there, so that engine’s indexed state means “indexed once, now frozen” rather than “current”. The report says so under the workspace header and on each affected engine, and names where to turn it on: Settings → Search indexing.
Read the state field with care. A value of indexed is satisfied by whatever the index already held before this crawl ever ran, so it cannot by itself answer whether this crawl actually ran. Whether last_indexed_at advanced is what proves a crawl served, and catalog_set_differs says the engine’s current catalogs are not the ones that were indexed — the honest way to say “a crawl is needed”.
Needs: a signed-in session or an API key, with query_engines:write — this is a read, but it is governed the same way the write verb below is, because it answers the question a crawl decision depends on.

dip crawl start

Dispatches a crawl now instead of waiting for the interval, and wakes any engine that has scaled to zero. Reports dispatch, not completion. Check dip crawl status afterward for the outcome. Dispatching nothing because no engine was eligible is not an error: it exits 0 and says why. (One exception: see the exit 3 row below for when zero dispatched actually means something else was already running.) --wait needs to be able to tell WHICH engine’s progress belongs to this crawl. Pass --engine to track one engine reliably. With neither --engine nor --integration (every eligible engine), dip can still track the whole crawl, as long as no engine was skipped. An --integration-scoped crawl with no --engine cannot be tracked at all. The crawl still runs, but --wait refuses outright (exit 3) rather than reporting an answer it cannot back up. If the integration is not federated onto any engine, the crawl itself dispatches nothing and exits 0 as an ordinary no-op (this is the one case where --wait never even runs, so its correlation limit does not apply). If a crawl covering the same engines is already running when --wait checks, dip waits for THAT one to settle before starting a new one. The index carries no per-crawl id, so starting on top of an in-progress crawl would leave no way to tell them apart afterward. Only once it is confirmed finished (or nothing was running to begin with) does dip dispatch and start watching. If this request instead gets folded into that already-running crawl (so nothing new is dispatched), --wait reports exit 3, not 0: that crawl’s completion does not prove a refresh that started with THIS command. What success actually proves, and what it does not. The index carries no way to tie a row back to a specific crawl, so --wait’s success means “the index for these engines refreshed after this crawl started”, not “this exact crawl is what refreshed it”. A different trigger racing this exact dispatch (another dip crawl start, the interval sweep, an engine apply’s own nudge) is not distinguishable from this one. The pre-dispatch check above only rules out a crawl already in flight, not one that starts at the same moment. --wait’s exit codes: Exit 3 is not a failure of the crawl. It means dip could not confirm the outcome in the time it watched, or could not confirm it at all. Nothing is cancelled: the crawl keeps running on its own, and dip crawl status reports the real outcome whenever it lands. The --json report. dispatched, workflow_ids and skipped are always present. final_status (the index status after --wait finished) is present ONLY when --wait was passed AND something was actually dispatched AND the wait ended in success (exit 0): it is absent when --wait was not passed, when the dispatch was a no-op, and whenever --wait ends in exit 1 or 3 (those return before the report is ever printed). Needs: a signed-in session or an API key, with query_engines:write and the data_admin role. --engine also needs query_engines:list, since resolving it to a specific engine lists this tenant’s engines to find it, whether or not --wait is passed. With --wait and neither --engine nor --integration, it needs query_engines:list too, for a different reason: confirming nothing was skipped before dispatching requires listing every engine. A credential missing that capability is refused before anything is sent.

Secrets

The secret store is write-only: no command here prints a stored value. See Secrets overview for what a secret is. Secrets need scopes that a default dip login does not carry; when one is missing, the refusal prints the dip login ... --scope command to run, or use an API key minted with them (see OAuth scopes). The commands that acquire something (dip secret set, request, bind and grant) first check that your tenant includes Secrets and stop with the "secrets" entitlement is not held in this workspace if it definitely does not. Listing and revoking never stop for that reason.

dip secret list

Lists the secrets you may see: name, handle (secret://<name>), kind, status, current version and how many bindings. Never a value. --name keeps secrets whose name contains the text. In --json, withheld is true when some secrets exist that you cannot see. Needs: secrets:read.

dip secret set

Stores a new secret. The value is read from a terminal prompt with echo off, asked twice, or from standard input with --stdin. There is deliberately no flag that takes the value, so it never reaches your shell history, ps or an AI agent’s transcript:
With --stdin, one trailing newline is dropped. The value must be between 1 byte and 64 KiB. Without --stdin and without a terminal, the command refuses and nothing is sent. It creates a new secret and is refused for a name already in use. Needs: secrets:write, and Secrets included in your tenant.

dip secret request

Asks a person to supply a value, and prints a link once. Give the link to the person who holds the value; they open it, sign in and type it, and you never see it. This is the command for an AI agent to use. The secret is created empty with the status Awaiting value. See Request a secret value. --json prints action, handle, request_id, status, expires_at, request_link and a note. The link works once and expires after 24 hours. Needs: secrets:write, and Secrets included in your tenant.

dip secret bind

Binds a secret to an app under an environment variable name. --env uses capital letters, digits and _, starting with a letter; PORT, HOME and names starting ALTIMATE_ are reserved. The binding records the handle, never the value. Delivery of bound secrets to running apps is not available yet. You need the use privilege on the secret. Needs: secrets:bind and secrets:read (dip looks the secret up by name), and Secrets included in your tenant.

dip secret grant

Gives a person or service user a per-secret privilege. --to is user:<id> or service:<id>. You need manage on the secret, and destinations as well to grant destinations. Needs: secrets:write, and Secrets included in your tenant.

dip secret revoke

Takes one privilege on one secret back from one person. You need manage on the secret. It works even when your tenant no longer includes Secrets. Needs: secrets:write.

Metrics

dip semantic list

Lists the governed metric inventory you may see: each model’s name, status, the table it computes over, and how many measures, metrics and dimensions it declares — not the definitions themselves. Each model also carries its id and a console_url: the model’s own console page, which is where a person with the certify privilege finds its Certify button. To find the metric that answers a specific question, or to read one model’s full definition, use the tenant’s MCP server (search_metadata, list_semantic_models, get_semantic_model) instead of this listing — it is an inventory, not a search surface. Needs: a signed-in session or an API key.

dip semantic example

Prints one complete, valid SemanticModel JSON document to standard output. It defines an example_avocado_prices model bound to the bundled avocado-prices sample dataset, with a time dimension, two plain dimensions, one measure for each of AGG_SUM, AGG_COUNT, AGG_COUNT_DISTINCT and AGG_AVG, a simple metric, two derived metrics (a change and a growth rate) and a conversion metric. AGG_MIN, AGG_MAX and AGG_PERCENTILE are also available; this example does not use them. Save it to a file and hand it straight to create --file to see the model land. To update an existing model with it, edit the name and fields first: update replaces the whole model, so an unedited copy of this example would rename and overwrite whatever you targeted. --json is accepted for consistency with the rest of this group. The output is the same document either way. The document is self-contained on purpose. It leaves out a relationship and a cumulative metric, because both need something else set up first: a relationship’s related model must already be certified, and a cumulative metric needs a time spine declared. It also leaves out AGG_PERCENTILE, which needs two values of its own on the measure (see below). Add any of these once its prerequisite is met. The altimate-onboarding agent skill that dip skill install adds shows a relationship and a cumulative metric, clearly labeled. The example reads from the catalog avocado_prices_sample, the name the sample dataset usually gets on your engine. Catalog names can differ, for example when two sources would get the same name. Check the catalog name in Explore and change catalog in the document if yours is different. Needs: nothing. It reads no tenant data and needs no login.

dip semantic create / import

Author a semantic model. create takes a complete SemanticModel JSON document; import takes an OSI document in YAML or JSON — the same documents the console accepts from the Import OSI document button on the models list (its dialog is titled Import an Open Semantic Interchange (OSI) document): a Dippr export (top-level model:, what the model page’s OSI document tab shows), an Open Semantic Interchange document (top-level datasets:), or OSI 0.1.x (top-level semantic_model:). Each OSI dataset becomes its own model; see how an OSI document becomes models for which relationships and metrics translate and which are skipped with a warning. --file - reads stdin. Every model lands as a draft, whatever the document’s own status says — certification is a person’s decision about these exact bytes, not a property of the file. The document imports whole or not at all: a definition that cannot compile (an unsupported aggregation, a malformed expression, a duplicate name, a dataset bound to a query) is refused by name, and nothing is created. The output lists every created model and each warning; --json reports them under models (and the first under model). The native (model:) OSI shape import reads binds its table through model.dataset.catalog / .schema / .table — not the top-level catalog field create/update and get_semantic_model use, which this shape does not read. dip semantic import --help embeds the smallest such document that imports:
A document shaped like create/update (or get_semantic_model’s output) simply wrapped under model: has its catalog field one level too high for native import to read, so dataset.catalog reads empty; the refusal names model.dataset.catalog and, when it detects that specific misplaced key, points at this shape instead of reporting the visible catalog value as empty. The document create and update take has a fixed shape. Get these right before writing one by hand, or start from dip semantic example, which already has them right:
  • The table a model computes over is three separate fields: catalog, schema_name and table_name. Never a single dotted string. A schema field, or a dotted table_name, is rejected.
  • Every enumerated value (an aggregation, a time grain, a filter operator, a relationship type, a metric type) is written exactly as the schema spells it: AGG_SUM, TIME_GRAIN_DAY, FILTER_OP_IN, RELATIONSHIP_TYPE_MANY_TO_ONE, METRIC_TYPE_SIMPLE, and so on. Never a shortened form. See Metrics for what each metric type computes. The reference document from dip semantic example shows a working aggregation, time grain and filter operator.
  • A filter’s dimension must always be written as model.name (example_avocado_prices.type). This holds even when the filter is on this same model; an unqualified dimension is refused. A metric reference (a ratio’s numerator or denominator, a derived metric’s inputs, a simple metric’s measure, a conversion’s base or conversion measure) may be written bare (total_volume) or qualified (example_avocado_prices.total_volume) when it names something on that same model. Both work. Only the filter dimension is required to be qualified.
  • A measure needs a time dimension to be grouped by time, one way or another: either its own agg_time_dimension, or the model’s default_agg_time_dimension as a fallback. Leaving both unset is refused when you propose the model, not only when a query later tries to group by time. Fix it before proposing, not after.
  • An AGG_PERCENTILE measure needs two values in its agg_params: percentile, strictly between 0 and 1 (0.5 is the median), and use_approximate_percentile set to true (Trino has no exact path here). Missing either one is refused when you propose the model.

Column types are filled from your engine

create and update fill in each dimension’s data_type (its Column type) for you. When a dimension leaves data_type empty and its expr is a bare column of the bound table, dip asks your query engine to describe that table and copies the column’s type, for example varchar, decimal(10,2) or timestamp(3) with time zone. A metric that filters a dimension by value needs its column type, so this saves you looking each one up.
  • A data_type you write in the document always wins.
  • A dimension whose expr is anything other than one column, such as upper(region) or a || b, is never guessed. It stays empty. So does an unquoted reserved word such as current_date, true or null, which Trino evaluates rather than reads from the table; quote it ("current_date") when it really is a column’s name.
  • The output says what was filled, such as filled data_type for 3 dimensions from DESCRIBE lakehouse.sales.orders on engine warehouse: region=varchar, .... --json lists each one under type_fill.filled, and any bare-column dimension left empty under type_fill.not_found. Expression dimensions are not described, so they appear in neither list.
  • The table is described on --engine, or on the workspace’s only engine, through that engine’s data plane MCP endpoint; --mcp-resource (or DIPPR_MCP_RESOURCE) overrides the derived endpoint for a dev cluster on a non-default port. It runs as you, so a column you cannot see is not described. On a dip login session, dip exchanges your login for the engine’s access, so there is no second sign-in. Where the workspace cannot do that exchange (an older control plane, or DIP_NO_PLANE_EXCHANGE is set), the describe never opens a browser: the types stay empty and the warning says to run dip mcp login once, after which the describe uses that sign-in.
  • If the table cannot be described (no engine, no access to the engine, a column the engine does not list), the model is still saved. A warning names every bare-column dimension left without a column type, so you can set data_type yourself before a metric filters it by value.
  • --no-fill-types sends the document’s types exactly as written and describes nothing.
Needs: a signed-in session that consented to semantic:author, or an API key minted with it. A session cached before this scope existed refreshes with another dip login. Filling column types also needs query_engines:execute_sql on the engine; without it the model is saved and the types are reported as left empty.

dip semantic update / delete

update replaces a model’s definition from a full JSON document (a certified model keeps its certified snapshot active while the editable head changes; editing a proposed model withdraws the proposal). update fills empty column types from your engine the same way create does. delete removes a model and its version history — it requires --yes, and the data_admin role. Neither is a certify verb. Needs: a signed-in session that consented to semantic:author, or an API key minted with it.
update, delete and propose look the model up by name (or id) before they change it. If one of them fails on a dip login session with the workspace did not accept your login for this call, first run dip whoami: if it shows the session has expired, dip login again. If the session is current, the workspace is most likely running an older version than your dip and does not yet accept a login for that lookup — a role grant will not change that. Retry after the workspace updates, or run the same command with an API key minted with semantic:author in DIPPR_API_KEY.

dip semantic propose

Snapshots a draft model as an immutable version and submits it for certification review — the author’s half of certification, and the last step a CLI credential takes. --note attaches a message for the reviewer. The output ends with the model’s console_url, the page to hand to whoever certifies it.
There is no dip semantic certify or dip semantic deprecate, and there will not be. A CLI or an agent drafts and proposes; a person blesses it in the console, on the model’s own page (Semantic layer → Models → the model) — the same rule a business concept follows. The Suggestions tab is a different queue: it holds metric and verified-query suggestions from agents, not proposed models.
Needs: a signed-in session that consented to semantic:author, or an API key minted with it.

dip semantic preview

Compiles a metric against a model’s draft head — the same preview an author sees when asking a metric question in Explore before it is certified — and shows the SQL it would produce. Add --run to execute that SQL on your query engine and print sample rows. The output always says draft, not certified: query_metrics over MCP still only accepts certified metrics, and this command does not change that. An invalid filter in an unrelated draft does not block your preview. The preview leaves that draft out and returns a warning naming it. If your query depends on the broken model, compilation stops with model "<name>" cannot be compiled and the reason; fix that model before retrying. On a dip login session, --run needs no second sign-in: dip gets a token for the engine’s data plane from your login, with no browser, the same way dip db does. You don’t need dip mcp login first. Only a workspace that cannot issue that token yet opens your browser once, for the same one-time approval described in When a dip db command asks for your approval. Needs the same privilege as editing the model: a signed-in session that consented to semantic:author (or an API key minted with it), with permission to edit this particular model. Without it, refused with a message naming the missing privilege — the same one the console’s own draft preview requires.

Business vocabulary

A concept is a real-world thing (Customer, Order, Shipment) with typed properties, relationships to other concepts, and bindings to the semantic models that realize it — the object that says a “Customer” held in two different tables is one concept, not two.

dip ontology list

Lists the ontologies: each namespace and how many concepts you may see in it. There is no paging here, because a tenant has only a handful of these. Needs: a signed-in session or an API key.

dip ontology concepts

Lists the concepts themselves: name, ontology, status, and how many properties and bindings each declares — the inventory, not the definitions.
A binding to a table you cannot read is left out of the count entirely, never shown as a redacted entry — a binding must never reveal that a table exists. So this count is “bindings visible to you”, not a tenant total, and two people can honestly see different numbers for the same concept.
Needs: a signed-in session or an API key.

dip ontology create / update / delete

Manages ontologies — namespaces with no lifecycle of their own. A non-empty ontology is refused rather than cascade-deleted, so removing a namespace can never destroy vocabulary without every concept in it passing through its own lifecycle first. Needs: the ontology-authoring credential (see The write credential below).

dip ontology concept create / update

Authors a concept, always as a draft — nothing consumes a draft, which is what makes agent-driven authoring safe.
An update replaces the whole document on the wire, so dip reads the concept back first and refuses the write outright if any of the concept’s bindings are hidden from your credential. Sending the document back would silently delete what you could not see. Use dip ontology import instead when that happens, or have someone with wider visibility make the edit.

dip ontology concept delete

Removes a concept. Refused while another concept’s relationship still points at it.

dip ontology concept propose

Snapshots the current definition as an immutable version and puts it up for review — the author’s half of certification, and the last step a CLI credential takes.

dip ontology import

Creates draft concepts from an OSI ontology: document in YAML — the way to author properties with descriptions and classifications, relationships, and bindings with property maps, none of which the flags above can express. --file - reads stdin. A name that already exists is refused, never merged. It accepts both Dippr’s own layout (each ontology: entry is a named ontology with concepts:) and the OSI ontology spec’s own layout (each entry is one concept:, a ValueType or an EntityType, as in the spec’s flights.yaml). A spec document lands as one ontology: the one --ontology names, or the document’s own name when the flag is omitted. Each EntityType becomes a concept, value types type their properties, a unary relationship becomes a boolean property, and ontology_mappings are not imported. Each one skipped is named in a note, up to the import’s limit of 100 notes (the rest are counted). Anything that would change a concept’s meaning if dropped (an n-ary relationship, an identifier made of an edge) refuses the whole document, naming the first 20 such elements. Export and import has the full translation. The smallest document that imports as-is, in Dippr’s own layout (dip ontology import --help prints this same example):
A property’s logical_type is the same closed set --property NAME=TYPE above accepts — boolean, date, integer, number, string, timestamp — matched case-insensitively, so STRING and string name the same type. Anything else is refused, naming the accepted set.
There is no certify or deprecate command, and there will not be. An agent may draft vocabulary; a person blesses it — the same rule a semantic model follows. Both actions stay in the console, at Semantic → Concepts. If you type dip ontology certify, dip ontology deprecate, dip ontology concept certify or dip ontology concept deprecate, dip refuses and points you to dip ontology concept propose, the author’s half.

The write credential for ontology authoring

Every dip ontology authoring verb accepts either a dip login session that consented to the authoring scope or an API key in DIPPR_API_KEY — the same as every other dip write. A session cached before ontology authoring existed does not carry the scope; running dip login again refreshes it, and a verb that reports a missing capability is telling you to do exactly that. In CI, where there is no browser, the API key remains the natural choice. The credential needs two capabilities: ontology:author to author vocabulary and semantic:compile to read the concept back (an authoring update replaces the whole document, so it reads first). A dip login explicitly consents to semantic:compile; an API key must be minted with both ticked. delete additionally needs the data_admin role.

Workspace databases

Load a file into your own database, ask a question in SQL, then share a named shared database:
The file name supplies the default table name, so sales.csv becomes sales. dip db --help starts with this path and groups connection, token and engine details under ADVANCED: CONNECTING YOUR OWN DUCKDB, TOKENS, ENGINES. A workspace database is a DuckDB database that lives in your tenant’s data plane. You write to it from your own machine over DuckDB’s remote protocol, and Trino reads it live as a catalog under ordinary governance; its owner can also write it with Trino SQL. Queries read the live database, so there is nothing to run between a write and a query. dip db publish and dip db load --publish / --no-publish are refused: they exit 1 with a message saying nothing is exported.
You write as yourself. The write verbs (create, connect, invite, tokens revoke, delete, exec) work on your ordinary dip login, which carries workspace_db:write and metadata:read. A session from an older dip, or one narrowed with --scope, lacks them: the first write opens your browser to grant them once and the session carries them thereafter (exec also consents on the plane, because its server-side database resolution reads metadata:read on your behalf). An API key in DIPPR_API_KEY minted with workspace_db:write is the headless alternative. The read listings (list, status’s record, tokens list) need metadata:read; on a session that lacks it, dip db status asks for it in the browser the first time, the same way a write does.
With no <name>, every verb acts on your personal database on that plane — one per member per plane, created automatically the first time you ask for it. Name a database to act on a shared one instead; dip db list shows the names.

dip db list

Lists the databases you own or belong to: kind (personal or shared), plane, and Trino catalog name. Creates nothing. When apply_pending is true, dip db list also checks the query engines with the same credential. If that read succeeds and the database’s plane has no engine, it says the database is ready. An engine is needed only to query it from apps or SQL tools through an engine; a data admin can create one with dip engine create --name N --plane P. The JSON database row includes engine_check: none, present, or failed. The field is absent when apply_pending is false. A failed engine read, an existing engine, or a database error keeps the conservative catalog-mount message; apply_pending itself is unchanged. Database errors remain visible in the text output and in last_error in JSON. Wherever a dip db --json report carries a database record (databases here, a database object in status, create and the others), its kind is personal or shared and its state is provisioning, ready, failed or destroying. A value this version of dip does not recognize (one a newer Dippr release added) is unknown, never a number. dip db sql --json and dip db exec --json carry only the database’s name, as the string database. Below them, under shared with you, it lists the databases another member shared with you to read with dip db share. You read those through the engine as their catalog, for example SELECT * FROM sales.main.orders from your agent or the console. They take no connection token, and dip db connect, load and sql on one answer that it is shared with you to read only, and how to read it. With --json, the report carries shared_with_you, each with name, sql_name, owner_email, access (always read) and a next_action sentence. When the shares cannot be read right now, shared_with_you_error says so; an empty list then means “unknown”, not “nothing”. The list holds at most 200 databases; shared_with_you_truncated is true when there are more, and --plane narrows it.

dip db create

Creates a shared database you own — not your personal one, which already exists implicitly. The response prints next commands using the new database’s unique SQL name, so they still resolve when another shared database has the same display name. Load a file with dip db load <sql-name> --from FILE, or invite writers with dip db invite <sql-name> <email>. Each of your shared databases on a data plane has its own name. If you already have one with the same name on that plane (ignoring case), dip db create creates nothing and exits 7. The message names the database you already have, with its ID and SQL name. Use that database, or run the command again with another name. Other members’ databases and your databases on other planes do not count, and neither does a database that is being deleted. Databases that already share a name stay as they are. Under --json, the response carries action, database, rules_cleared and name_withheld, and no engine fields: creating a database changes no engine’s catalogs. Whether an engine has mounted the new database yet is reported by dip db status. rules_cleared is true when the create removed row filters or column masks it found on the new database’s catalog name (Dippr does not know who set them; typically a deleted database of that name left them), and false otherwise; without --json the command says so in a sentence. A new database always starts with no filters or masks on its name, so set them after creating it. name_withheld is true when the name you asked for still carries filters or masks and could not be shown to be unused (a query engine has it mounted for another catalog, or some query engine in the workspace is still serving a catalog Dippr has no current name for). It is false for the ordinary case of a name another registered catalog already has, which also gets a short id added, whether or not that name carries rules: the database is then given the name with a short id added, the rules are left alone, and the command says what to do, since a catalog name cannot be changed later. See Deleting a database. If Dippr cannot check for filters and masks on the name, or cannot remove them, the create fails with unavailable, creates nothing, and can be run again. The first command that creates your personal database prints the same sentences on standard error. Under --json the error envelope has class name_taken, code already_exists, an existing_ids list (oldest first) and a next_action you can pass to a person as is:

dip db connect

Prints the two statements your DuckDB needs to attach the database, composed server-side so the console, the CLI and any MCP tool never disagree on the address. If you have a file to load, start with dip db load --from FILE instead. The token is shown once, at mint time; a lost token is re-minted, not recovered. The text output ends with the command that revokes that token, and --json carries the same command as revoke_command. It names the database’s id whenever you named a database, and carries --plane and --workspace when you passed them, so run it as printed: it revokes the token on the database it was minted on. Your own DuckDB must be exactly 2.0.0, the build your databases run: any other build fails to attach. dip db duckdb fetches that build.

dip db invite

Lets another member write to a shared database. Name them by the email they use in your tenant; if they have not yet accepted an invitation to your tenant, dip cannot tell that apart from nobody having invited them, so it refuses with … is not a member of this workspace yet. This only grants write access to the database itself. It does not let them read the catalog in Trino: dip db share does that. The person’s role must allow shared databases (analyst or above). A viewer has only their own personal database, so inviting one is refused and nothing changes; the message names the two ways forward: ask an admin to give them analyst, or let them read the database with dip db share. While any row filter or column mask covers a table in the database’s catalog, only its owner can write to it. Write access reads the rows directly, around those rules, so inviting anyone is refused and an invited member’s dip db connect is refused. When the rule is added, the people already invited are removed from the database before the rule is reported as saved: their tokens stop working and the database restarts, which ends open connections, the owner’s included. Once the rule is gone, the owner can invite them again. Share read access instead: reads through the engine apply the rules.

dip db share / dip db unshare / dip db shares

dip db share lets one member of your tenant read a database you own in Trino. They get SELECT on the database’s catalog and nothing else. Only the database’s owner can share it, the person must already be a member of your tenant (sharing never invites anyone), and the database’s catalog must exist, which it does once the database has started serving. The share is an ordinary read grant: an admin sees it under Settings → Roles and can remove it there. You can never share more than you can read yourself. Sharing again with someone who already has access changes nothing and reports unchanged. dip db unshare takes the access back, by email or by the user: id that dip db shares --json prints (use the id for someone who has since left your tenant). dip db shares lists who can read the database because you shared it. With --json, share prints action (shared or unchanged), principal, email, role_id, catalog, the database record and a next_action sentence. unshare prints action (unshared or unchanged), principal, database and next_action, plus email when you passed one. shares prints database, role_id, catalog and shares, each with principal and email. share and unshare take --json, --workspace, and --browser-wait / --no-browser, which bound or refuse the one-time browser approval they may ask for; shares takes --json and --workspace. Any other flag is refused before anything changes.

dip db tokens list / dip db tokens revoke

Lists your own connection tokens, or revokes one by the id tokens list prints. A token’s label names the machine that minted it by its short host name only (dip on laptop), so a cloud VM’s internal domain never reaches the workspace. Set DIP_TOKEN_LABEL to choose the name yourself. Each token line shows its label, expiry and state, and a last used time only when the platform has recorded one. No plane reports token use yet, so today that time is absent. An absent time means unknown, not never used. The line above the tokens names the database and, once it is serving, its connection address. By default the list shows only tokens that can still open a connection. Every dip db sql and dip db load creates a one-hour token that is never revoked, so most of your tokens are expired ones. When the list leaves some out, it says so, and --json reports "hidden_inactive": true. Add --all to include expired and revoked tokens. The platform deletes a token 7 days after it expired or was revoked, so --all never shows one older than that.
A revoked token stops authenticating new connections once the database picks up the revocation, which can take a short while, and a session already attached with it may stay attached and keep reading and writing: revocation is connection-scoped, and the protocol has no way to end one session. Revoking also asks the platform to restart that database’s instance to end such sessions, but nothing confirms the restart reached them, and an attached session has been seen to survive a revoke. When the restart does happen, anyone else connected to that database is disconnected too.

dip db status

Reports one database in full: quota and usage, its table list with row counts and, for each table, the quoted reference to query it by (in SQL as "<catalog>"."main"."orders"; use it verbatim, since a schema or table name that needs quoting is already quoted), whether an engine still has to mount its catalog (apply_pending, true until every engine on its data plane has applied its catalog). After an upgrade, if apply_pending is true for a database you can already query, have someone who manages the affected engine click Apply, then check its status again. The command also reports its catalog name read back from the engine (catalog, or catalog_pending with the sql_name to expect). The connect address is internal plumbing, so it is shown only with --verbose (dip db connect prints it where you need it, and --json always carries quack_uri). metadata:read reads the record, and query_engines:execute_sql reads the table list from your own data plane’s MCP endpoint (it is the current list, where an attached client only sees the tables that existed when it attached). It runs on an alt_ API key in $DIPPR_API_KEY, or on your dip login. The first time you run it on a login that isn’t allowed to use workspace databases yet, it opens your browser for the same one-time approval every dip db write asks for, then prints the result (see When a dip db command asks for your approval; --no-browser makes it fail at once instead). With no <name>, that first run also creates your personal database, as any first use does. On a login, dip never sends your login token to the plane: it gets a token for that plane from your login, with no browser. If your workspace cannot issue one yet, it uses the plane consent you gave dip db exec (or dip mcp login), and without one it prints the record and a tables line saying to run dip db exec once. It never opens a browser for the table list. With metadata:read but not query_engines:execute_sql the record still prints and the tables line names the capability to add; an unreachable plane reports the endpoint and operation that failed — neither tells you to re-run the command. With no <name> it acts on your personal database, which (like dip db connect) also needs workspace_db:write; a named shared database needs only metadata:read for the record. If the table list cannot be read, the text says could not read the table list. Under --json, tables_unavailable is true, tables is an empty array, and tables_error contains the error once, including the request ID when supplied. A successful read of an empty database returns tables: []. The report has no table_count: the live table list is tables. Consent advice appears only when authentication or a required capability is missing; other tool failures retain their own message and next action when supplied. A failed table read does not mean a load failed. Verify the rows through your engine using the database’s catalog name. The in SQL line, and catalog and engine in --json, is the catalog name the query engine mounted, read through your data plane. Until an engine has mounted the database it reads NOT MOUNTED YET with the name to expect (catalog_pending: true and sql_name in --json). SQL through a query engine sees loaded rows once it has mounted the catalog. Read dip db status (name a shared database), or workspace_db_list through MCP, and follow the catalog reason. While catalog_mount_in_progress is true, the engine is mounting catalogs: check again in about a minute. If no restart is running, check again after a minute; if unchanged, someone who manages the engine can apply its catalogs with your approval. A stopped engine picks up catalogs within about 10 minutes without starting. For a busy engine, relay the admin step and Query engines list link first, then the timing. If another apply is running, check its result first. Applying restarts the engine and fails its running queries. If the data plane cannot report the mount state, the line says could not read the catalog mount state and catalog_pending is null. If it reports the mount state but cannot list tables, the known mount state is still shown. If the platform declined to restart the engine to mount it automatically (see Catalogs and Apply), the line says so and gives the reason, for example that someone else used the engine in the last 30 minutes; --json carries that reason as auto_apply_reason. Follow catalog_reason: when your role cannot apply, it describes the recorded idle wait, if available, and asks a tenant admin to apply now instead of offering you the apply command. Applying restarts the engine and fails its running queries. When the data plane has several engines, the line also names each other engine that has not mounted the database yet, with the platform’s reason when it declined to restart that engine; --json lists them in unmounted_engines (engine, auto_apply_reason, and next_step when your role cannot apply, which the line also shows). --json also carries the data plane’s expected_catalog, the name to expect on engine whether or not it is mounted, and engines: each engine on the data plane that has a name for the database, mounted or not, with its own engine, catalog, mounted and auto_apply_reason. Catalog names are per engine, so match catalog to the engine you query. Both are left out when the data plane could not be asked.
A database’s catalog is readable, and writable with Trino SQL, only by its owner until someone is granted it by name. Every other member, admins and people invited to write the database included, needs a read grant that names the catalog (dip db share, or an admin’s grant on it) before they can read it in Trino; until then their query is denied. A share never lets them write it in Trino.

dip db exec

For a database still being created on first use — your personal one, or a named database (including a shared one) right after dip db create — exec waits up to 90 seconds before running the statement. With an API key and your personal database, dip prints “creating your personal database, about 90 seconds” while it waits; for a named database, the wait happens on the platform and the command simply takes longer to return. If it is still being created after 90 seconds, try the command again in a minute.
Runs one SQL statement against the database on the platform’s own connection — the write path that needs no attached DuckDB client. Because it runs server-side, the client-binder surprises below do not apply: INSERT, CREATE TABLE, UPDATE, DELETE, ALTER and CREATE SCHEMA all run as written, and the single statement is wrapped in BEGIN/COMMIT for you.
Quote the whole statement so your shell passes it as one argument; with no <name> it targets your personal database, and a name targets a shared one, which the tool resolves server-side. It is exactly one statement per call — for more than a few thousand rows, dip db connect and streaming a file in from your own DuckDB is far faster. The rows are in the next Trino query’s result, because engines read the database live; the only wait is a new database’s catalog being mounted once (see When your database becomes queryable). The line under the result says that the next SQL query on the database’s catalog sees the rows, and that dip db status shows the catalog name. A schema change (CREATE, ALTER, DROP) says instead that the change is live, and shows a rows changed line only for a CREATE TABLE … AS SELECT, where it is the number of rows loaded. When no query engine on the data plane serves the database’s catalog yet (a tenant with no engine, or a new database not mounted yet), the line says instead that the write is saved and that SQL queries see it once an engine has mounted the catalog, points at dip db status and dip engine list, and adds the reason when there is one. --json carries next_step exactly as the write tool returns it to an agent, unchanged. There is no command to run after a write, so the report has no next_command field.
Unlike the other write verbs, exec reaches the database over the data plane’s MCP endpoint. On a dip login, dip gets that plane’s token from your login, with no browser, and gets a new one when it expires. If your workspace cannot issue one yet, the first run opens a one-time browser consent for workspace_db:write bound to that plane instead, and that token is cached and renewed silently. Set DIP_NO_PLANE_EXCHANGE=1 to always use the browser consent. It works on any data plane, including one with no query engine yet. That consent covers workspace_db:write, query_engines:execute_sql (to resolve a named database to a unique id before writing; it also clears the connection floor) and metadata:read (the write’s server-side database resolution reads the metadata:read-gated plane surface on your behalf). An alt_ key in DIPPR_API_KEY is presented directly, with no browser step; a key holds workspace_db:write, query_engines:list and metadata:read. --plane is honored (a named database is matched only on the selected plane, never silently repointed to a same-named one elsewhere); resolving the plane — for --plane or the personal form (no name) — lists data planes, which needs no particular capability. --mcp-resource overrides the composed endpoint for a dev cluster.
If exec fails with the statement did not run: the data plane could not look up …, the statement never reached your database: the platform refused to find the database for you, and nothing was written. The message ends with the platform’s reason. Fixing the SQL won’t help; tell your administrator what it says. A message that starts the workspace database refused this statement is the database itself rejecting the SQL. If the platform could not connect to your database’s server at all, exec says the statement did not run: the workspace database server could not be dialled …. Nothing was sent, so running the same command again in a minute is safe; --json reports may_have_landed: false. If the connection broke after the statement was sent, the outcome is UNKNOWN: the write may have landed, so read it back with the SELECT the message suggests before running it again. In both cases the platform logs the technical reason and the message does not include internal server addresses.

dip db import inspect and dip db import learn

Inspect a saved MCP result and verify a local import recipe. A recipe is a JSON description of the rows, output columns, row identity, pagination and count to check. These commands prepare a recipe on your machine; they do not load a table or make any data available to colleagues. inspect prints the result’s structure, stable field IDs and sanitized field names. It omits scalar values. Field names can themselves contain source data, such as an email address used as an object key. Sanitizing names and assigning stable IDs does not anonymize those keys. Keep inspection reports private, and use sources with fixed field names when keys must not reveal source data. Use the IDs to propose the recipe’s field paths, and choose the output column names yourself. Paths select fields or array elements; recipes cannot contain SQL or file-reading expressions. Optional fields and failed conversions must be declared explicitly. If inspection reports that the structure is too large, fetch a smaller source page and inspect it again. If even one record exceeds the limit, request fewer fields or a simpler source result. No partial inspection report is returned. Start with a small page that has another page after it. Run learn with the first call ID to obtain the next request, call that tool through the same source connection, then run learn again with both call IDs. The next request repeats the base request arguments and adds the cursor; it does not contain the page’s rows. learn checks the tool, request arguments, declared source identity, cursor progress, row identities, column conversions and any exact total. A verified recipe is saved privately for your local user, under its fingerprint. Raw pages and source details stay on your machine. The report starts with status: "inspected" for inspection. The first learning pass returns status: "needs_next_page", pagination: "advance_unobserved" and next_request. Successful two-page learning returns status: "learned", pagination: "advance_observed" and a fingerprint. The count is exact_available or unavailable. Learning verifies a cursor transition; it does not certify that you fetched every row. The recipe accepts only these fields: The Claude Code version is not checked; the saved result must use a notice format dip recognizes. Inline results, error results and previews are refused. This refusal applies to dip db import; a small complete inline result can use the bounded MCP copy instead. Do not retry an error by asking the source to print its rows. A source tool’s anthropic/maxResultSizeChars setting can keep rows inline or reveal a preview before dip sees them; lowering MAX_MCP_OUTPUT_TOKENS does not override that setting. See Prepare an import recipe.

dip db import page, finish and recovery

Collect verified saved pages privately, then publish the recipe’s typed columns to your personal workspace database. An import is a named local collection of pages checked with one verified recipe. Use the fingerprint returned by learn and the same source-account label for every page. page needs no database connection. Repeating an accepted page with identical content changes no rows; different content for the same page is refused. Start a new import for changed source data. While pagination is unknown, page and status print next_request (the tool and its arguments, as learn does): the first request while that page is missing, otherwise the base request with the cursor the last connected page returned. It never contains row values. An exhausted or broken import prints none. finish requires your personal database’s UUID and a new table name. Get the UUID from dip db status --json. The database must be empty or contain only tables managed by imports on this machine and their import control table. Shared databases, another person’s database, unrelated tables or views, and an existing table without its local import record are refused. You can continue collecting local pages while resolving a destination refusal. The complete page set must have exhausted pagination and contain no duplicate row identities, source errors or rejected conversions. The report keeps count and pagination separate: verified, unavailable or mismatch for count (pending for an exact count until the last page arrives); exhausted, unknown or broken for pagination. If the source provides no exact count, review the collected pages and pass --confirm-count-unavailable once to record your confirmation. It does not override unknown pagination or an integrity error. Conversion-failure reports give counts, never rejected values. Once finishing starts, the import is sealed: its pages, recipe and destination cannot change. outcome_unknown means the database may have committed the publication without returning its answer; finish and resume exit with status 3 in that case. Keep the local files and run resume; it checks the recorded publication without automatically publishing again. If the database remains unavailable, leave the import unresolved and resume when it is reachable. A competing newer publication, including one that lands while finish is still reading the database, is refused as a conflict without overwriting it, and that import’s pages must be collected again under a new import ID. A failure before the publication was sent is reported as rolled back; run finish again to retry with the same pages. Original pages and local preparation files remain private on this machine after publication. status reads the local record, including a separate integrity verdict. abort cancels local unfinished work; it never undoes a published table, and it first checks an uncertain publication and refuses while that remains unresolved. sweep acts on imports untouched for 30 days: it deletes aborted and conflicting imports, and for a published import it deletes the pages and staging but keeps the small local record, which the next finish needs to recognise and replace that table. Unresolved imports are never touched. Cleanup deletes files; it does not securely erase them. Only the recipe’s named typed columns reach the table. Readers can also see main._dip_import_control, which contains table names and opaque publication identifiers. Raw pages, source-account labels and rejected values are never uploaded. Share read access explicitly after checking the result; see Publish saved pages.

dip db load

Loads files, or the result of a query, into a table, using the DuckDB built into dip. It reads the files on your machine and streams the rows into the database. Nothing passes through object storage, and the credential it mints for the attach is never printed.
For CSV input through --from, dip warns if the file parses as one column whose name contains a comma, semicolon, tab or pipe, or if a column has a name such as column7 that may have been assigned automatically. These can indicate a misread delimiter or a missing header. Warnings appear in text output and in the warnings array with --json, including during --dry-run. A warning keeps the exit status at 0 unless you pass --strict, which exits with status 1 before writing. With --strict --json, the refusal contains error.class: "usage", error.message and the warnings array. Review the file and preview its columns before loading it. These checks do not validate arbitrary queries passed with --sql. An intentional header such as column7 also triggers the automatic-name warning. If the database is still being created — your personal one on first use, or a shared one you just ran dip db create on — load waits up to 90 seconds for it and says how long it waited, rather than attaching immediately and reporting a network failure. --no-wait opts out and fails right away. dip db sql reads the loaded rows now. SQL through a query engine sees them once it has mounted the database’s catalog, which the platform normally does by itself; after that, engines read the database live, so the next query sees new rows. For a pending mount, the load’s next step points to dip engine list for the engine’s sync state and prints the exact dip db status command that shows the mounted catalog. --no-publish / --publish are refused by name. See Load data. Exit status 4 means dip and the workspace database run different DuckDB builds (run dip update), and 6 that the database could not be reached from this machine. A Quack authorization refusal, including a quota restriction, is ambiguous: exit 1, class refused. dip db exec receives an explicit quota refusal and reports exit 5, class quota_exceeded. A load stopped after it prints loading …, by Ctrl-C or by killing dip, may still land in full: the database can commit the statement it already received. On Ctrl-C dip cancels the statement and closes its connection (waiting up to ten seconds), then prints a warning saying so. If a killed load left its table refusing writes with Catalog write-write conflict, wait: the database usually ends the dead connection within about two minutes. If it is still refused after five, see Verify and recover a load. Verify that the original load has finished and whether it landed before retrying. If an append landed, do not replay it. Retry an append only after confirming it finished without adding rows; if its outcome is still uncertain, stop. Use --mode replace only with a source containing the full intended table, including all pre-existing rows. Never replace an append with only the appended source. See Verify and recover a load. When a CSV text column mostly contains date shapes, dip warns, for example, column "order_date" looks like dates but loaded as text (mixed or ambiguous date formats); dip did not guess the day/month order. It reads the first 1,000 rows once and warns, for each text column, when at least two non-null values, and at least half of them, look like dates. This check also runs with --dry-run and --format csv. Sampling errors skip the check. Values stay as text; dip does not guess whether 01/05/2024 means January 5 or May 1. Confirm the intended format before converting. For day/month/year text, use strptime with --sql and the required --table:
Replace FILE with your path. This recipe requires every non-null value to use that format; normalize mixed formats first, or explicitly handle each confirmed format in SQL. The warning appears as a warning: line and in JSON warnings; --strict refuses it before writing rows. These date checks apply to CSV --from loads, not Excel, JSON, Parquet or caller-supplied --sql.

dip db sql

Runs SQL against the database from the DuckDB built into dip, attached the same way as load. Reads, writes and transactions work as written, unqualified table names resolve in the database, and local files are readable too, which makes it the place to look at a file before loading it. The SQL comes from --sql, a --file, or standard input; dip never prompts. It prints at most --max-rows rows (default 1000, 0 for all) and says when there were more. Like load, sql waits up to 90 seconds for a database that is still being created (--no-wait opts out). A DATE prints as 2024-01-01, a TIME as 13:14:15.5 (a TIMETZ with its offset, 13:14:15.5+02:00) and a TIMESTAMP as 2024-01-01T13:14:15.123456, without a zone suffix it never had; a TIMESTAMPTZ is an instant and prints in RFC 3339, for example 2024-01-01T13:14:15Z. A date or time inside a STRUCT, LIST or MAP still prints in RFC 3339. In --json output NaN, Infinity and -Infinity (at any depth) are the strings "NaN", "Infinity" and "-Infinity", a UUID column is its text, a BLOB is base64, and a MAP is a JSON object, or an array of [key, value] pairs when a key is not a string. A UUID nested in a LIST, STRUCT or MAP is not converted and prints as base64: cast it to VARCHAR.
--local runs the SQL on your machine with no database attached. It needs no sign-in, never opens a browser and makes no call to your tenant, so it is the way to look at a file before you have a database to load it into. It can’t be combined with a database name, --plane or --workspace.

When a dip db command asks for your approval

The first time a dip db command needs a permission your login doesn’t have yet, it opens your browser so you can approve it, then carries on. How long it waits depends on who is watching: With --json, a stopped approval reports class: credential, a reason of consent_required (--no-browser) or consent_timed_out, the exact missing_scopes, and a next_action you can pass on to a person as written. An API key in DIPPR_API_KEY never needs a browser.

dip db duckdb

Fetches exactly the DuckDB build your databases run, 2.0.0 (once, into dip’s own cache, verified against a pinned checksum) and prints its absolute path. It exists so the large-file accelerator works with zero manual install and so a pyenv/asdf shim on your PATH can never shadow it: dip invokes the cached binary by absolute path.
The version is pinned; a download whose checksum does not match is discarded and nothing is installed. On a platform dip ships no pinned build for, it prints the manual install line instead. dip db duckdb --help prints this command’s own help.

dip db delete

Stops serving the database. Refuses without --yes. A deleted database is unreachable from the product: no dip command, console page or MCP tool can read, list or restore it. --discard-data reclaims your tenant’s pod and disk on the plane when this was the plane’s last workspace database; without it the pod stays for your next database. Nothing is exported either way. Snapshots exported before the export was removed stay in your workspace’s object storage under the legacy prefix _altimate/wsdb/<tenant>/dbs/<database>/snapshots/ and are removed with the tenant. Every engine that had the database’s catalog mounted keeps listing it until its catalogs are applied. dip db delete waits (about a minute) and reports what happened: Dippr applies it for you when the restart affects nobody else (the automatic apply), and otherwise it says why the platform did not restart the engine (“Not restarted automatically: …”) and prints the exact dip engine apply <name> --yes command. dip db delete --yes never forces that restart itself. It only confirms the delete, so it never restarts an engine someone else is using. --no-apply skips the wait and reports the delete without checking engines. Under --json, the response carries a pending_engine_apply boolean (true whenever at least one engine may still list the deleted database’s catalog), an auto_apply array with the platform’s decision for each engine reached, and apply_commands with the exact command for any engine still pending.

What your own DuckDB will let you write

On the pinned build, an attached database behaves like a local one:
  • Reads, writes (UPDATE, DELETE, ALTER and CREATE SCHEMA included) and transactions run as you type them. A BEGIN/ROLLBACK on your own connection rolls back.
  • Your client sees the tables that existed when it attached. A table someone else creates later is not visible until you DETACH and attach again; dip db status shows the current list.
dip db exec runs a statement on the platform’s own connection instead, the write path to reach for when you do not want to attach DuckDB at all.

Which capability each verb needs

db load and db sql mint a database token the way db connect does and write with the DuckDB built into dip, so they need nothing beyond workspace_db:write. On a dip login, db exec writes through the data plane’s MCP endpoint, with a token dip gets for that plane from your login (no browser). A workspace that cannot issue one yet opens one browser consent for that endpoint on the first run instead. Either way the token carries workspace_db:write, query_engines:execute_sql (to look a named database up to its id before writing) and metadata:read (so the plane can find the database for you). On a session from an older dip, or one narrowed with --scope, the first db write also grants the login itself workspace_db:write and metadata:read. With an alt_ key, db exec needs workspace_db:write plus query_engines:list, the connection floor every call to the plane’s MCP endpoint must clear (workspace_db:write implies no read scope), and a named one also needs metadata:read. db delete and removing a member additionally require you to be the database’s owner or hold the data_admin role. Some forms list data planes first: the unnamed personal forms — db connect, db load, db sql, db status, db tokens list, db tokens revoke with no database name — always resolve your personal database’s plane, and any db command given --plane (including db list --plane and db create --plane) resolves that plane by name. A named db command without --plane lists no planes. Listing data planes needs no particular capability: any signed-in credential may do it, so an alt_ key minted for loading data into your personal database holds workspace_db:write and nothing for publishing apps. (A workspace that has not yet been updated still asks for apps:publish here.) Separately, db status’s per-table listing runs SQL, so it needs query_engines:execute_sql.

Plane files

dip file puts any file in your tenant’s object storage and gets it back. The file goes straight from your machine to storage; nothing opens or parses it. See Upload and download files.
upload and rm need files:write; list and get need files:read. When you are signed in with dip login, the first dip file command opens your browser once and asks for both, so you approve reading and writing your own files together. That one approval covers all four commands on that data plane until it ends, and the next dip file command after that asks once more. It ends when you or an admin revoke it, or when it expires: after 30 days by default, or after the shorter or longer period your workspace is set up with (see offline_access). It covers both directions even if you only ever list: after approving, dip on this machine can also upload and delete your files there, the same way one approval covers reading and writing your workspace database. It never reaches anyone else’s files. You approve once for each data plane you use, and dip whoami --json lists the approval under mcp_tokens with the kind files. With --no-browser (or DIP_NO_BROWSER=1) a command that would need the approval fails at once and names the two permissions instead of opening anything. If an MCP file tool refuses a request for missing permission on a standard OAuth connection, use dip file list and the other dip file commands in a terminal instead; dip asks you to approve once in the browser if it needs to. For an API-key connection missing a file permission, the refusal instead says to use a workspace API key minted with that permission. An API key in $DIPPR_API_KEY works too and is never asked to approve anything: it can do only what it was minted with, so a key with files:read alone can list and download but not upload or delete. Mint it with query_engines:list as well, and use --plane to pick a plane. --mcp-resource (or $DIPPR_MCP_RESOURCE) names the plane’s MCP endpoint directly when dip cannot look planes up; do not combine it with --plane. When the plane refuses a command, for example a get of a file that is not yours or does not exist, dip prints the plane’s own sentence and what to do next. With --json the sentence is message, the step is next_action, and request_id is the id to quote to an admin.

Governance

dip governance changes who can see what in your tenant: the data grants, and the row filters and column masks that narrow them, that the console shows on Settings → Roles. Your roles decide whether you may use it, exactly as in the console: in the built-in roles only account_admin can, and an admin can delegate it to a custom role. A member whose roles do not allow a change is refused, and nothing changes. The first time you run one of these commands on a dip login session, dip opens your browser once to ask for permission to manage governance (governance:manage). An ordinary dip login does not ask for it. To run them in CI, set DIPPR_API_KEY to an API key minted with governance:manage for a service user whose role allows the change. If nobody approves that browser prompt in time, dip tells you to run the same command again and approve the page it opens. It does not tell you to run dip login again, since an ordinary login never requests governance:manage and would leave you stuck. Retrying the original command (for example dip governance effective ana@example.com) reopens the same on-demand consent. The dip governance commands take the same two options as the other commands that ask for a permission on first use: Running a grant, revoke, or a row-filter or mask change again with the same arguments changes nothing and reports unchanged, so a script of these commands is safe to re-run. A row-filter set or mask set with the same arguments is still sent to the workspace, for the reason dip governance row-filter gives. If a set answers that the rule is saved but invited writers are not yet confirmed disconnected, run the same command again.

dip governance list

Lists every direct privilege grant for the named role in your tenant, including Documents folder grants. Prints the object kind, folder or object name, permission, allow or deny effect, and grant identifier. --json returns an array with id, role, role_id, entity_type, entity_ref, privilege, and effect fields. An empty role returns [] with --json, or “No privilege grants.” in text output. This reads grants without changing them and uses the same governance permission as the other commands.

dip governance grant

Gives a role a privilege on one object. The change applies to everyone holding the role, on their next query. The report’s action is created, updated (an existing rule switched between allow and deny, with previous_effect) or unchanged. A built-in role keeps the grants it ships with, so the tenant refuses a grant on one and nothing changes. To give its members more access, create a custom role that inherits it, grant there, and assign the custom role to those members: a grant on the custom role doesn’t reach anyone who holds only the built-in role. The one exception is the Own personal database row on viewer (--on PersonalWorkspaceDatabase, privilege read, create or update), which you can switch with --deny and back; --json marks that change with role_builtin: true. A DocumentFolder grant names one Documents folder in the tenant. Use a custom role: built-in roles cannot take these grants. The folder reference must be 1 to 63 lowercase letters, digits, underscores or hyphens, starting with a letter or digit; an empty reference and * are refused. The accepted privilege names are read, add and manage. Each grant records an explicit ALLOW or DENY effect. Grants and revokes appear in the access log.

dip governance revoke

Removes one grant, named the same way as grant or by the id that grant --json and effective --json print. Revoking a grant that does not exist reports unchanged. A grant the platform seeded on a built-in role cannot be revoked; the tenant refuses it and says so. A built-in role can also hold a grant it doesn’t ship with; an admin (account_admin or data_admin) can revoke that one. Anyone else is refused, and nothing changes.

dip governance row-filter

A row filter (row-level security) limits the rows of one table a role’s members see. --where is a SQL condition, such as "region = 'EU'", that is added to every query those members run against the table. A role has at most one filter per table, so set on a table that already has one replaces its condition and reports updated with previous_expression. set with the same condition reports unchanged, and remove of a filter that does not exist reports unchanged. set with the same condition still asks the workspace, because on a catalog that is a workspace database it is how you finish a set that could not yet confirm the database’s invited writers were disconnected. A set can take up to a minute to answer for that reason.

dip governance mask

A column mask replaces one column’s value for a role’s members. --expression is SQL of the same type as the column, such as "'***'" or "substr(ssn, 8)". A role has at most one mask per column, and set and remove report created, updated, removed or unchanged the same way as row filters.
Admins are exempt from row filters and column masks: a member holding account_admin or data_admin sees every row and the real values, whatever filters and masks their roles carry (see Roles and permissions). A filter or mask can still be set on account_admin, data_admin, or a role that inherits one, but it restricts no one. set saves it, prints a warning that says so, and --json reports the same sentence in warning. A rule restricts a person only when they hold no admin role, directly or through inheritance: put it on a role they hold that is not an admin role, and remove any admin role they hold.

dip member invite

Invites a person to your tenant and prints their one-time invitation link, the same link Settings → Users → Invite user shows. Repeat --role for more than one role; with none, the invitee joins as viewer. It needs the Members · create privilege (account_admin holds it), and you can only grant roles within your own authority. Spaces around a --role value are ignored, and a blank value is refused before anything is sent. Role names are case-sensitive. An unknown name is refused with the available roles and, for a case-only mismatch, a suggested spelling. The credential needs members:invite. A current dip login already holds it and needs no prompt. An older or narrowed login opens your browser for members:invite only. --no-browser (or DIP_NO_BROWSER=1) refuses instead and names members:invite; --browser-wait D controls the wait as described above. In CI, use an API key minted with members:invite for a service user whose roles allow inviting. A key holding only governance:manage cannot invite. A person who already has a Dippr account must also sign in and accept the invitation before they join. When dip can check the member list, an email that already belongs to a member reports unchanged and creates no link. A login checks only if it already holds governance:manage; an API key attempts the check and skips it if access is refused. Neither asks for extra permission. When the check is skipped, dip says it did not check. An existing member who accepts gains no membership or role. An invitation that has not been accepted yet is not visible to dip, so inviting that person again makes a new link and the earlier one keeps working until it is used or expires. --json prints {"action", "workspace", "email", "roles", "invite_id", "invite_url", "expires_at", "agent_prompt", "member", "member_checked"}. invite_url carries a one-time secret: hand it only to the person you invited. member_checked says whether dip checked the member list. When it invites someone, the text output ends with a line they can paste into their AI after they join, and agent_prompt carries the same line: it names your tenant’s address and nothing secret, so it is safe to share.

dip governance effective

Reports what one member can actually reach: every role they hold, including inherited ones, the combined grants, where a deny wins, and the row filters and column masks that bind them, each naming the role it comes from (an inherited role’s rules apply just like a direct role’s). Where several of the member’s roles mask one column, only the mask the engine applies is listed. An admin is shown as exempt from filters and masks. If you may not list rules, the report says they are not shown rather than “none”. Give a member’s email, or a service user’s service: id.
--json prints one document with exact ids: {"action", "workspace", "grant": {"id", "role", "role_id", "entity_type", "entity_ref", "privilege", "effect"}} for grant and revoke, and {"workspace", "member", "roles", "grants", "row_filters", "column_masks"} for effective (rules_exempt for an admin; rules_unavailable instead of the two lists when they can’t be read). A row filter reports {"action", "workspace", "row_filter": {"id", "role", "role_id", "catalog", "schema", "table", "expression"}} and a mask {"action", "workspace", "column_mask": {…, "column", "mask_expression"}}; list prints {"workspace", "row_filters"} or {"workspace", "column_masks"}.

Plane-local Git

dip git supplies short-lived credentials and signing material to stock Git. It never configures a global credential helper and never handles GitHub or GitLab credentials.
dip git clone invokes stock Git with a credential helper configured only for that clone. dip git remote adds an independent remote without storing credentials; GitHub and GitLab remotes remain outside Dippr and are never mirrored. dip git push resolves the remote old OID and local new commit OID, obtains a one-use signing grant for that exact ref update, and sends its signed owner attestation with a Git signed-push certificate. Because write does not imply read, the login needs both git:read and git:write. Use --provenance for an agent, app, or automation origin marker that the platform can carry into the repository event and use for self-trigger suppression. Do not put credentials or source content in this marker. dip git credential implements Git’s get and erase helper operations. get answers only an HTTPS request whose host exactly matches --host; every other host gets an empty response. erase stores nothing, and store is refused. Returned credentials expire within 15 minutes. For a plane served on a non-default HTTPS port, include it in --host, for example acme.git.dev.lvh.me:8443. dip git keeps :8443 when deriving the plane domain dev.lvh.me:8443; an explicit :443 is treated the same as omitting the port. dip git sign runs the command after -- with a one-use SSH key and allowed-signers file scoped to the repository and ref. Both files use owner-only permissions and are removed when the command ends. See Plane-local Git for clone, push, protection, and revocation behavior.

Keeping dip current

dip version

Prints the CLI version (also the bundled SDK version) and the platform it was built for.

dip update

Replaces this binary with a newer release, verifying its checksum before swapping anything. Updates download the resolved release and its checksums from a versioned location on your selected mirror. Missing versioned files stop the update and leave the installed binary unchanged. Betas are prereleases, tagged like v0.9.0-beta.1. They never move the stable channel, so automatic updates never install one and a plain dip update refuses to jump onto a beta. Install a beta only by naming its exact tag — dip update --version v0.9.0-beta.1, or DIP_VERSION when you run the install script — which pins to it. A plain dip update later clears the pin and installs the current stable release, returning you to the stable channel. See Beta / prerelease versions. dip also checks for updates by itself: at most once a day, before an ordinary command, and only at an interactive terminal. See Install dip and sign in for the full behavior.

dip telemetry

dip sends anonymous usage and failure reports to Azure Application Insights. Telemetry is on by default from your first dip command. The reports include:
  • Command start and completion, duration and exit status; aborted commands and crashes.
  • Request completion and retries, including timing, attempt counts and status.
  • Milestones for login, updates, app creation, checks, builds, pushes, development sessions and dip doctor, plus skill and MCP installation.
  • First-run and dropped-telemetry events.
Failures carry an error class and fingerprint, never the error message. Reports use fixed categories and measurements; no free-text paths, hostnames, names or tokens are sent. Your tenant is recorded as a one-way hash, never the URL itself. Run dip telemetry --help for the CLI’s disclosure. The complete list of events and properties dip sends is on dip telemetry data. The first time dip runs at an interactive terminal on a machine, it prints this once, to stderr:
Two environment variables turn it off without running a command: DIP_TELEMETRY=0 and the cross-tool convention DO_NOT_TRACK=1. Either one wins over dip telemetry on. See Environment variables dip reads for how these behave in a pipeline. Needs: nothing.

Capability reference

Two independent things gate every write verb: a capability (a scope fixed on your credential at login or at API-key mint time) and a role (changeable any time under Settings → Roles). Missing either one is a refusal, and the fix differs — a missing capability means re-signing in or re-minting a key; a missing role means asking an admin to grant one. Roles inherit upward: viewer → analyst → data_engineer → data_admin.
crawl status is a read, but it does not ride the search-index read capability — it shares query_engines:write with the write verbs, because the platform treats reading crawl state as part of the same governed surface as triggering one. A credential scoped only for search reads gets a refusal here that has nothing to do with your role.

Errors and --json

When a command fails, dip says what kind of answer the tenant gave, because each kind needs a different next step. When the tenant answered (it refused the change, or found no such record), dip reports that answer using the tenant’s own sentence. Only a tenant that could not be reached is reported as a connectivity problem. A failed write has an unknown outcome in three cases: the tenant could not be reached (unreachable), it answered with an internal error (server_error), or it was out of capacity or rate-limiting the call (rate_limited). In those cases, read the state back before you re-run: the read-back the message names (for dip db exec, a SELECT against the same database; for dip db load, dip db status), or else the matching list command. dip integration test is not one of these writes: it changes nothing, so a failed probe is always safe to re-run. A credential failure has one of these causes, and each needs a different fix. The message says which one it is, and under --json the envelope’s reason field names it. Commands that list --json in their help keep stdout machine-readable when they fail. Stdout carries exactly one JSON document, the error envelope below, and the explanation still goes to stderr. Commands that do not list --json never write a JSON document. Five of them refuse --json like any other flag they do not take: dip plane prove, dip pipeline push, dip pipeline register, dip mcp uninstall and dip app check. The other commands without --json ignore it and print their usual output. Passing --json does not change the exit status: most failures exit 1, and a --wait that could not establish the outcome exits 3 with an inconclusive envelope, and db exec exits 5 for an explicit quota refusal; db load / db sql exit 4 or 6 for version skew or an unreachable database. Their Quack quota refusal is ambiguous and exits 1, refused, and db create exits 7 for a name you already have. In db load and db sql against a workspace database, one request may wait up to 9 minutes for the server’s answer. A statement the server runs without sending anything back, such as a load whose source reads nothing on your machine, is one request: if it runs longer it ends with exit 6 and a message saying a request got no answer within 9 minutes, and it may still finish on the server. Asking for help (dip --help, dip -h, dip help, dip <command> --help) prints the help to stdout and exits 0. A usage exit, such as an unknown subcommand, exits 2, and under --json it also writes a usage envelope, because its help text goes to stderr. A usage envelope does not mean the exit status is 2: a missing flag detected by the command itself is also usage and exits 1. Anything after a bare -- is an argument, not a flag, so a --json there does not count. The exception is -h and --help: for a command dip recognises, either token anywhere on the line, after a bare -- and in a flag’s value position included, asks for that command’s help, which prints to stdout with exit 0 and runs nothing (so a separate --help argument is always a help request; an inline --flag=--help, such as dip db sql --file=--help, is a value). An unrecognised subcommand with --help is still a usage error.
  • message is the tenant’s own sentence, without the wire code. There are two exceptions. For a usage error it is dip’s sentence. When may_have_landed is true it is dip’s full explanation, which includes the tenant’s sentence and names the read-back to run before a replay.
  • A Docker failure during dip app push includes a bounded, sanitized build-output tail (omitted when the log exceeds 64 KiB) and local log path in message, including with --verbose. Identified connection failures use unreachable and supply retry guidance in next_action; authentication failures use credential, registry refusals use refused, and build/conformance failures retain usage. may_have_landed: true means the upload outcome is unknown. Check the registry before retrying. See Build and push an image for diagnostic limits and log handling.
  • reason appears only when class is credential, and names the cause from the table above.
  • next_action appears when dip knows the one step to take, for example “Ask a workspace admin to make this change.” when dip governance refuses a member whose roles do not allow the change. You can pass it to a person as written.
  • request_id, attempts and at are optional. dip stamps them on single requests to the tenant’s control plane. They are usually absent in three cases: a streamed request (dip pipeline events), an OAuth token refresh the server answered with an error, and a request to a data plane’s MCP endpoint (dip db exec, db status). A request ID means dip generated one, not that the request left your machine. When the platform received it, it logs it, so quote it when you report a problem.
  • may_have_landed is the authoritative answer to “might the change exist?”, whatever the class. It is true when the failing call was the write itself and its outcome is unknown (unreachable, server_error or rate_limited), and also when a failure came after the write was already dispatched, which can carry any class. When it is true, read the state back as the message says before you re-run. It is always false when the failure came from a lookup dip makes before the write, or from dip integration test. The field is absent from errors where dip does not know whether the failing call was a write.
Two commands write a JSON result that itself reports the failure. That result is the one document on stdout, and no error envelope follows it:
  • dip integration test --json when the probe fails. The result holds the connection details and the source’s own error.
  • dip doctor --json when a check fails. The report names the check.
Both exit 1. A command that streams several documents, such as dip pipeline events --json, ends the stream with the error envelope if it fails.

dip CLI overview

What dip is, who uses it, and how it signs you in.

Using dip in CI

Build and push a data app from a pipeline with an API key.

Agent commands

dip agent build [--dir DIR] [--tag TAG] builds an agent image from manifest.json and agent.py: with your own Dockerfile in the directory it uses that, and without one it builds on a generated Dockerfile with the SDK bundled in dip and an optional requirements.txt installed. See Author an agent. dip agent push [--dir DIR] [--registry HOST] [--slug SLUG] [--tag TAG] [--platform LIST] [--workspace URL] pushes the image and registers its immutable digest. It builds linux/amd64,linux/arm64 unless --platform narrows it, for example --platform linux/amd64 on a dev stack, where the arm64 half under emulation dominates the time. A single-architecture image runs only on nodes of that architecture. Publication needs apps:publish and agents:publish. A default dip login carries agents:run and routines:read. Agent publication remains separate: the first dip agent command that needs agents:publish opens your browser once to request it, preserves your existing grant, and saves the result. An older or narrowed login can also request a missing execution scope when needed. Add --no-browser to be told what is missing instead, or --browser-wait DUR to bound the wait. An alt_ API key is used as it is. Agents and pipelines are included in the standard tenant entitlement bundle. A platform administrator can disable either feature; an upgrade preserves that choice. Agent installations still need consent and a budget before you can run them. dip agent list [--workspace URL] shows the published catalog’s agent IDs. dip agent push registers a new agent ID or updates an existing ID when its manifest version increases. dip has no install or review command: install an agent, set its consent and budget, start tasks and review paused writes on the console’s Agents page (Run and review agents). The console does not display installation IDs; to run an installation from dip, take its ID from AgentService.ListAgentInstallations. Given an installation ID, find the query engine UUID with dip engine list, then run dip agent run <installation-id> --engine-id UUID --prompt TEXT [--json] [--workspace URL] to create a task on that engine and follow its content until it stops or pauses for review. Default output shows readable conversation text and successful result summaries, items, evidence, and coverage. Use --json for the unchanged raw JSON event lines. Long content histories renew the viewer capability and resume from the last event. Ctrl-C or SIGTERM requests remote task cancellation; if the request fails, dip prints the task ID and says it may still run. A successful cancellation records the final state at once, while the agent’s sandbox finishes stopping shortly after. dip agent dev [--dir DIR] [--port PORT] --prompt TEXT [--trinoproxy-url URL] [--egress-proxy-url URL] runs one local turn of the agent and prints its events. Omit --prompt to serve the agent for manual development. Local turns use a placeholder token; a live query or egress probe also needs ALTIMATE_AGENT_DEV_TOKEN in the environment and the corresponding --trinoproxy-url or --egress-proxy-url. A tenant without the agents entitlement cannot use this group: dip agent --help is refused there too, and dip login does not install the altimate-agent skill. Author an agent explains the manifest, access ceiling and review flow.

Routines

A routine is a saved investigation that runs with a person’s access. Use a dip login session; API keys cannot use these commands. Each command targets one tenant, supports --json and --workspace URL, and returns a nonzero exit on refusal or failure.
Routine commands use your dip login session, even when DIPPR_API_KEY is set. API keys cannot call these commands. list returns up to 50 records. Pass its nextPageToken as --cursor TOKEN to continue. runs returns up to 50 recent records with status, failure or missed reason, execution identity, advisory spend in microdollars and duration in milliseconds when a task exists. An absent measurement is unavailable. save uploads your instruction and saves pending work. Choose daily, weekdays or weekly with an explicit time and IANA timezone. Weekly work also needs --weekday 1 to 7 (Monday to Sunday). --outcome names the work; --description is optional. For a pending draft saved without --start, the owner confirms in a fresh console session before scheduled checks begin. list and show include outcome and description in their JSON. The outcome names the work, for example “No order ships late”. Older unnamed routines show their subject or “Untitled work”. dip routines is an alias for dip routine. The optional list --state filter accepts pending_activation, active, paused, blocked or dismissed. The default list excludes dismissed drafts; dismissed lists only your own. Dismiss requires --reason not_useful, --reason already_covered or --reason other and works only on your never-activated pending draft. Restore keeps its instruction and returns it to pending activation, requiring fresh console confirmation. Both require agents:run. Your dismissal never hides a colleague’s suggestion. suggest starts Dippr’s built-in routine runner in the background, as you, to save up to three pending suggestions from data you can see; it requires agents:run and --engine, and --timezone (default UTC) sets their weekday 09:00 schedule. suggestions reads your latest run, or --run <run-id>, and requires routines:read: state is running, done (with addedCount) or failed (with failureReason), and withheld is true when some data was not visible to you. You can have one suggestion run at a time. Reads require routines:read; run-now, pause and resume require agents:run and the same owner or administrator permissions as the console. run-now uses the saved instruction and existing authorization without changing the next scheduled time. Resume works only on an already confirmed routine; pending activation requires a fresh console sign-in. You can also pass --browser-wait DUR and --no-browser for sign-in consent. Every failed routine run carries a stable failure code and a plain-language reason that any viewer of the run can read; the person whose access ran the check also sees the routine’s own message on a second Details: line. dip routine runs and dip routine show include reasons in text and --json output; get_routine_run and list_routine_runs include them, with failure_code, for AI follow-up.

Personal work start and proposal authority

dip routine save --start starts new personal work without a console confirmation, records Started and requests one immediate first check. Without --start, it saves a pending draft. New work is read only; add --may-propose to enable proposals. Scheduled writes still require the owner’s approval in the console; dip and MCP bearers cannot approve them. The CLI generates a request ID before saving and prints it for recovery. Reuse --request-id UUID with the identical inputs after a lost response; do not start a fresh logical save to retry one. Use dip routine show <routine-id> --json to inspect the actual state and work log. dip routine authority <routine-id> --mode read-only --expected-version N narrows proposal authority. --mode may-propose enables proposals and records the change. Use the version from routine show. A version mismatch refuses the update. dip routine pause <routine-id> stops future launches. The plural aliases dip routines save and dip routines authority accept the same flags and have the same behavior as dip routine save and dip routine authority.

Routine report details

A routine receipt can include progress (on_track, needs_you or blocked) and a reason, an assumptions list, and data_freshness per table. These are model reports, not measured execution status or verified facts. Assumptions remain tentative and do not stop work by themselves. A freshness entry identifies the table, timestamp column, newest timestamp reportedly seen and supporting query reference. An empty or missing timestamp means unknown; even a recent value does not prove that the whole source is current. Older reports can omit these fields. Read the receipt with get_routine_run, or use dip routine runs <routine-id> --json and dip routine show <routine-id> --json. The commands include reports keyed by task ID. CLI report content requires agents:run consent in addition to routines:read; a narrowed login keeps metadata and receives a re-consent command for missing report access. Report content uses your own access; an unavailable report is disclosed while operational run metadata remains visible. Other people’s report details remain private. Preserve coverage.withheld when interpreting progress: on_track does not turn a partial report into an all-clear. Re-read relevant rows before describing a reported claim as verified.

Automation caps and guidance

  • dip routine budget <routine-id> --expected-version <version> --max-cost-usd-per-run <USD|inherit> changes the owner’s stored cap. The effective cap cannot exceed the installation ceiling.
  • dip routine guidance <routine-id> --json reads owner-private durable guidance.
  • dip routine guidance <routine-id> --expected-version <version> --entries-file <path> --json replaces its entries from a JSON map; {} clears them. Read first and preserve other entries. Stale versions are refused.
The plural aliases dip routines budget and dip routines guidance accept the same flags and have the same behavior as their dip routine forms. See spend caps and owner guidance.