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.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 loginsession: 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--workspacenorDIPPR_URLnames 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(orDIPPR_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 exits1:
--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-yesis refused:dipflags 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
usageerror: 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-runis refused, because--dry-runwould 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-runincluded, sodip skill uninstall --dry-runremoves 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, anddip pipeline new,check,dev,buildandsdk-sync. None of them changes a source, engine, database, grant or pipeline in your tenant. Some do contact it:dip loginanddip mcp loginsign in,dip mcp tokenrenews a sign-in that is about to expire, anddip whoami,dip doctoranddip mcp listread from it. Check the spelling of--planeand--workspaceon those, because a mistyped one falls back to the default.
Signing in
dip login
Needs: nothing (this is the sign-in step itself).
dip whoami
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
--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
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
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
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.dip mcp uninstall
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
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
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
dip skill install
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
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.
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
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
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:
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.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
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.
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.
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:
--registry/DIPPR_REGISTRY— whatever you name, taken as given. Also set--slugwhen the host does not already carry your tenant’s slug (a foreign registry such asghcr.io).- Several available registries with a named default: that default automatically, including on a terminal.
- 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 HOSTto choose explicitly. - If no choice was made from the current plane list, the registry your session saved at login.
- Nothing cached and exactly one available plane: that plane’s registry.
- No saved registry: the registries your tenant publishes about itself, with its default preferred.
dip app status
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
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:
--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:
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
Eachdip 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.pydeclares a version other than the published one; pipeline.jsonhere 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
--registrynames a different registry. A registry you passed todip login --registrydoes not count unless you pass it to this command too. A pipeline pushed with--tagto another registry, such as GitHub or ECR, cannot be sent again this way:dipreads 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
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
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.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
.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.jsonthen 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,cookieorsignature, or ends inkey, 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, everyvalueon 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 exampleValue:firstthensecond}OKon 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_…), anotheralt_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.jsoninstead of being written unredacted.
manifest.json records "value_redaction": false: only the name and
shape rules applied.
Needs: kubectl and helm on your PATH, with read access to the plane’s namespace.
dip plane keygen
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
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
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 assync 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_errorwhilelast_sync_statusis stillsyncedorpending. 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 assync note ..., notsync 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.
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
--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
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
--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
--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
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
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.
Needs: a signed-in session or an API key, with integrations:write.
dip integration update
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.
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.
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.
Needs: a signed-in session or an API key, with integrations:write.
dip integration test
--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
--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 as a read-only catalog.
- 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;
--yesrestarts the engine anyway, which stops the queries running on it. - Waits until the engine reports the new catalog set as synced, or reports the sync error and exits non-zero.
- 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.
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
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.
dip doc search
--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
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.
Metadata search
dip crawl status
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”.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
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 defaultdip 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
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
--stdin. There is deliberately no flag that takes the value, so it never reaches your shell history, ps or an AI agent’s transcript:
--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
--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
--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
--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
manage on the secret. It works even when your tenant no longer includes Secrets.
Needs: secrets:write.
Metrics
dip semantic list
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
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
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:
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_nameandtable_name. Never a single dotted string. Aschemafield, or a dottedtable_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 fromdip semantic exampleshows 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’sdefault_agg_time_dimensionas 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_PERCENTILEmeasure needs two values in itsagg_params:percentile, strictly between 0 and 1 (0.5 is the median), anduse_approximate_percentileset totrue(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_typeyou write in the document always wins. - A dimension whose
expris anything other than one column, such asupper(region)ora || b, is never guessed. It stays empty. So does an unquoted reserved word such ascurrent_date,trueornull, 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, ....--jsonlists each one undertype_fill.filled, and any bare-column dimension left empty undertype_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(orDIPPR_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 adip loginsession, 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, orDIP_NO_PLANE_EXCHANGEis set), the describe never opens a browser: the types stay empty and the warning says to rundip mcp loginonce, 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_typeyourself before a metric filters it by value. --no-fill-typessends the document’s types exactly as written and describes nothing.
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
--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.semantic:author, or an API key minted with it.
dip semantic preview
--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
dip ontology concepts
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.
dip ontology create / update / delete
dip ontology concept create / update
dip ontology concept delete
dip ontology concept propose
dip ontology import
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):
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
Everydip 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: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.<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
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
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
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
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
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.
dip db status
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.
INSERT, CREATE TABLE, UPDATE, DELETE, ALTER and CREATE SCHEMA all run as
written, and the single statement is wrapped in BEGIN/COMMIT for you.
<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.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 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
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
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.
--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:
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
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
PATH can never shadow it: dip
invokes the cached binary by absolute path.
dip db duckdb --help prints this command’s own help.
dip db delete
--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,ALTERandCREATE SCHEMAincluded) and transactions run as you type them. ABEGIN/ROLLBACKon 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
DETACHand attach again;dip db statusshows 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
--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
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
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
--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
--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.
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
--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
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
dip update
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.
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.
messageis the tenant’s own sentence, without the wire code. There are two exceptions. For ausageerror it is dip’s sentence. Whenmay_have_landedistrueit 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 pushincludes a bounded, sanitized build-output tail (omitted when the log exceeds 64 KiB) and local log path inmessage, including with--verbose. Identified connection failures useunreachableand supply retry guidance innext_action; authentication failures usecredential, registry refusals userefused, and build/conformance failures retainusage.may_have_landed: truemeans the upload outcome is unknown. Check the registry before retrying. See Build and push an image for diagnostic limits and log handling. reasonappears only whenclassiscredential, and names the cause from the table above.next_actionappears when dip knows the one step to take, for example “Ask a workspace admin to make this change.” whendip governancerefuses a member whose roles do not allow the change. You can pass it to a person as written.request_id,attemptsandatare 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_landedis the authoritative answer to “might the change exist?”, whatever the class. It istruewhen the failing call was the write itself and its outcome is unknown (unreachable,server_errororrate_limited), and also when a failure came after the write was already dispatched, which can carry any class. When it istrue, read the state back as the message says before you re-run. It is alwaysfalsewhen the failure came from a lookup dip makes before the write, or fromdip 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 --jsonwhen the probe fails. The result holds the connection details and the source’s own error.dip doctor --jsonwhen a check fails. The report names the check.
1. A command that streams several documents, such as dip pipeline events --json, ends
the stream with the error envelope if it fails.Related
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 adip 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.
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 includeprogress (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> --jsonreads owner-private durable guidance.dip routine guidance <routine-id> --expected-version <version> --entries-file <path> --jsonreplaces its entries from a JSON map;{}clears them. Read first and preserve other entries. Stale versions are refused.
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.