dip is Dippr’s command-line tool for signing in to your tenant, running queries, and building and
shipping data apps from a terminal or a CI job. Install it with one command, then sign in to connect it
to your tenant.
Let your coding agent connect
Give Claude Code your tenant URL and ask it to help you connect. Your tenant provides instructions your agent can read before you sign in, including how to installdip for your
tenant’s release.
To copy a ready-made prompt, open Overview → Get started: the card leads with it. Pick your
agent, click Copy prompt (or Open in Claude Code ↗), then paste it into the agent. The
prompt includes your tenant URL and its connection instructions. Once the card sees your dip login
it swaps in a continuation prompt for the restarted agent session. The same prompt is under
Set up by hand instead → Bring your terminal and AI tool, and after setup is complete on your
tenant’s is live card. If you hid the setup card, click Show setup guide on Overview to
reopen it.
The manual setup prompt includes the command that installs dip for your tenant’s release. It
uses the PowerShell command when you open the page on Windows and the macOS and Linux command
otherwise; choose the other system under Install to switch. Claude Code may refuse an installer
it only found in your tenant’s instructions. Putting the command in your own message lets Claude
Code consider it as your request, with its usual checks.
You can also open Connect your AI tool on your tenant’s sign-in page to read those instructions.
Your agent runs dip login with your tenant URL. Complete sign-in and approve access in the
browser when it opens. Keep your password and your data out of the chat.
After signing in, start a new Claude Code conversation in the same folder and ask your question again. The card’s manual Claude Code
setup is an alternative for connecting without dip login; you do not need both.
Installing the binary
Downloads show a progress bar only when stderr goes to a terminal. Captured stderr suppresses the bar while preserving final download errors. One command, no repository clone and no account needed — released binaries are published to a public downloads bucket.- macOS / Linux
- Windows (PowerShell)
dip — by default into $HOME/.local/bin, which needs no elevated
permissions.
dip carries its own DuckDB, the one your workspace databases run, so you can load and query data
locally with nothing else installed. What that means per platform:
Four environment variables steer the install:
dip carries, for example
duckdb: 2.0.0 (d54cbbe3df), embedded. On Windows on Arm it reads
not embedded in this build.
The first time any
dip command runs at an interactive terminal on a machine, it prints one line
telling you it sends anonymous usage reports, and how to check or turn that off:
dip: anonymous usage telemetry is on — what is sent: dip telemetry status; off: dip telemetry off or DIP_TELEMETRY=0.
See dip telemetry for what is sent and how to turn it off.dip keeps itself current
You install once. After that, at most once a day, and only when you are at an interactive terminal,dip checks the bucket it was installed from for a newer release, verifies it against the release’s
checksums, replaces itself, and re-runs the exact command you typed on the new binary — two lines on
stderr are the only sign it happened.
Installers and updates resolve the stable release once, then download that version’s binary and
checksums from the same mirror. A release published during your download does not change the version
you receive. If your mirror is missing that version, the download fails; it does not fall back to
another version. An automatic update failure leaves your existing binary in place.
--check reads a workspace when you pass --workspace, set DIPPR_URL, or have exactly one cached
login. With no selected workspace, it compares with the published stable release.
The automatic check never runs when DIP_NO_UPDATE_CHECK or CI is set, when there is no
interactive terminal, for dip update / dip version / dip help themselves, or when your install
is pinned to a tag — and it never downgrades you on its own. A failed check never fails the command
you actually ran.
Beta / prerelease versions
Some releases are betas: prereleases with a version likev0.9.0-beta.1. A beta is never installed
on its own. It does not move the stable channel, so the daily self-update never picks one up, and a
plain dip update refuses to jump onto a beta. You reach a beta only by asking for it by exact tag.
Pin to a beta in one of two ways:
dip records the pin, so the daily check stays on that beta and does not move you off it.
If your tenant runs a beta release, you do not need to know the tag. The Get started page and
the Apps publish steps in the console show the exact install command for your tenant’s version,
already set up to install that beta — copy it and run it.
dip update. It clears the pin and installs the current stable
release, returning you to the stable channel — even though that stable version is older than the beta
you were pinned to (leaving a prerelease is the one case where a plain update moves you to an older
version). From then on you track stable auto-updates again.
Upgrading from adp
dip was previously called adp, before the product’s rename to Dippr. The rename is a clean break:
- There is no
adpalias and no fallback for the oldADP_*environment variables. - Your existing
adpsessions do not carry over. Rundip login <workspace-url>again. - Rename any
ADP_*variables in your scripts, dotfiles and CI to theirDIP_equivalents (ADP_BASE_URL→DIP_BASE_URL,ADP_VERSION→DIP_VERSION,ADP_INSTALL_DIR→DIP_INSTALL_DIR,ADP_NO_UPDATE_CHECK→DIP_NO_UPDATE_CHECK). - Delete your old
adpbinary. Left on yourPATH, it keeps trying its own daily update check, finds nothing to download (the new releases publishdip-*assets, notadp-*), and reports a failure that following its own advice cannot fix. Removing the binary is the only way to stop it. - If you scaffolded a
frontendapp with the old CLI, its local dev setup still sends a request header under its old name. Updatex-adp-dev-keytox-dip-dev-keyin your app’s configuration, ordip app devrefuses that app’s requests.
Signing in
1
Run dip login with your tenant URL
Pass the URL you see in your browser’s address bar when you are signed in to the console. If you
omit it,
dip uses --workspace or the DIPPR_URL environment variable instead.2
Your browser opens
Sign in the same way you would to the console.
dip is not asking for a password of its own:
it is starting the same OAuth sign-in the console uses. The terminal shows the sign-in address
without OAuth parameters. If your browser cannot open, dip prints the full link to paste into
another browser.3
dip confirms the sign-in
Once you approve, the browser redirects back to
dip and it prints the tenant you are now
signed in to.
Extra approval tabs can be closed; return to your terminal to check the sign-in outcome.4
Skills and the MCP server are set up for you
The last two things
dip login does are installing the bundled agent skills into your home
directory, and registering this tenant’s MCP server with the coding agents on your machine.
See Connecting your coding agent below. Pass --no-skills or --no-mcp to
skip either step; a failure in either is a warning, never a failed login.No tenant yet: sign up with dip login
dip login the account address instead of a tenant URL, or run dip login with no address,
which uses https://app.us.dippr.ai. This is also what a coding agent runs when you ask it to sign
you up.
- Your browser opens the account sign-in. Sign in, or sign up with a new account.
- Pick one of your tenants, or create your first one: the page suggests an address you can edit. Approve.
dipthen signs the terminal in to that tenant. Approve once more in the same browser; you are already signed in. From here on it is the ordinary sign-in above, skills and MCP setup included.
https://mcp.<plane-domain>, works in place of the account
address. This path is for a first tenant: picking a tenant that lives on another data plane is
refused (invalid_target); sign in to that one with dip login <tenant-url>. If the account address answers that it offers no sign-up from the terminal, sign up at
https://app.<domain>/signup in the browser, then run dip login with the tenant URL it shows.
Approving the sign-in in your browser also completes the Bring your terminal and AI tool step
on the Overview page’s Get started card, so you do not have to mark it by hand. This is
remembered per browser: if you run
dip login in a different browser or profile from the one
showing the card, that step stays open there until you sign in with dip in the same browser (or
mark it with I already have dip).dip login again for a tenant you are already signed in to keeps the MCP sign-ins you
granted separately with dip mcp login or a dip db consent that carry a refresh token, and the
login says how many it kept. A separate sign-in granted without a refresh token is removed; run
dip mcp login again for it.
A sign-in is kept only when it belongs to the user you just signed in as. One you approved in a
browser signed in to a different account, or any sign-in after you switch users, is removed, and the
login says how many. Claude Code’s sign-in token, which came from the old login, is dropped and
replaced with one from the new login.
You can be signed in to more than one tenant at once — each one caches its own session. Most
commands take --workspace <url> (or the DIPPR_URL environment variable) when you need to say
which one you mean.
A normal login requests apps:publish and apps:install so you can publish your own app and install
it without another login. The browser describes publication and installation separately. A saved or
narrowed login gains neither silently: if installation names a missing apps:install capability,
run dip login <workspace-url> and review the consent screen. --scope still requests exactly
the names you supply. Installing a particular app has a separate access and code-trust confirmation.
See Install the app you built.
Normal dip login and dip mcp login also request agents:run and routines:read, so an analyst can discover a consented runner, test an investigation and propose a pending routine. Your roles still govern every action. Explicitly starting new personal work needs no console confirmation. Pending drafts and existing per-person subscriptions keep their console confirmation steps. For an older or narrowed login, sign in again and reconnect an AI session that retains its old token.
Normal dip login also requests agents:review, the separate permission to approve, reject or ask for changes to a write an agent proposes; the consent screen shows it as Approve changes agents propose. agents:run does not include it. dip mcp login does not request it, because an MCP connection’s token never carries approval. A sign-in made before agents:review existed keeps working for everything else but cannot approve outside the console until you run dip login <workspace-url> again. dip itself has no review command; approve in the console’s task view. Against a tenant whose server does not offer agents:review yet, dip login signs in without it and says so.
dip whoami
user:<id>; --json always carries principal, such as user:<id>, and email when known), whether the
session is still live and when it expires, and which capabilities you consented to on this machine. The endpoints the tenant
publishes for its data planes are internal hosts: --verbose lists them and --json always carries them. It also reports this binary’s version next to the latest one
published, and lists what your credential cannot read at all (for example, which users have which
roles) alongside the console page that does show it.
A dev (unstamped) build — a plain local go build, with no release tag stamped in — cannot be
ordered against a release at all: it could be ahead of every release or years behind. whoami says
comparison is unavailable rather than guessing, and never suggests dip update for it; name an
exact release with dip update --version <tag> if you want one.
A valid dip login credential calling an operation that is not open to dip login
credentials gets HTTP 403 permission_denied with this message:
dip mcp login for a data plane, or run dip db exec against a workspace
database on one, whoami shows that plane’s cached token(s) too, one line per token, each labeled by
what it is for (an MCP token, a database write token, or a database load token from an older dip), with the
capabilities it carries and when it expires. When Claude Code signs in to a plane with your dip login,
its cached token appears as a Claude Code sign-in (from dip login) line (dip_login in
--json). That token is not one dip mcp token can print: Claude Code gets a fresh one from your
login when it needs one. Only a line labeled MCP token (agent_mcp in --json) is what
dip mcp token hands out. whoami does not renew these tokens, so a line can show a past expiry
while every command still works. Each line says what happens next:
In
--json, each mcp_tokens entry carries renews: true when dip renews that token itself.
The Claude Code sign-in and the database write token are renewed from your dip login, so they
renew for as long as that login does.
If you signed in before a capability joined the default sign-in, or narrowed the sign-in with
--scope, whoami adds a missing line that names what a new sign-in would add and prints the
command to run, dip login with your workspace address. --json lists the same capabilities as
missing_default_scopes. Permissions a command asks for when it needs them, such as the file
permissions, are never listed there.
What whoami says stays in the console
whoami names what your credential cannot list from the command line, with the console page that
shows it:
--offline is unique to dip whoami among the read commands: it reports only what is cached on this
machine, including the consented capabilities and any cached MCP tokens, with no network call at
all. Every other read command needs to reach the tenant live.
Signing out
Rundip logout to remove the local tenant session and its cached MCP tokens. It also revokes the
sign-in on the server. Pass --workspace URL to select a tenant or --all to sign out of every
cached tenant. With one cached session, no URL is needed. Revocation failures are warnings: local
sign-out still completes, and you can revoke the connection at /settings/connected-apps in the
console. --offline removes the session locally without revoking it on the server.
MCP registrations stay until you run dip mcp uninstall --agent all --workspace URL, which also
works after logout. Logout lists the recorded servers and prints that command with the tenant’s
URL. Connections using your dip login stop working until you sign in again. Claude Code’s own MCP
sign-ins, made with /mcp OAuth rather than dip, are managed in Claude Code.
Git credentials use your sign-in
dip git credential refreshes a short-lived Git credential through your existing dip sign-in.
The credential is valid for no more than 15 minutes and only for the exact Dippr Git host and
repository. Signing in does not install a global Git helper and does not send Dippr credentials to
GitHub or GitLab. See Plane-local Git.
dip doctor
dip engine list is the next step to see what you can query. The command that fixes each unmet requirement appears below the
groups:
dip app build, dip app push or dip app check stops for Docker, so the report and the commands
always agree. Docker’s own error text stays out of the way; when the engine is not answering, set
DIP_VERBOSE=1 to see it, or read the --json output.
Every row’s status is one of:
The
missing versus not ok distinction matters: you do not need docker to run dip app dev,
and you do not need python3 to ship a TypeScript app, so a tool you have not installed is reported
with what it gates rather than as a failure. Only a broken requirement fails the command, and it
exits non-zero exactly then — so dip doctor && dip app push is a usable check in a script.
What each row checks
emulation reads unknown in two cases that a dip app push fixes. Before your first push, the
row’s detail says the builder does not exist yet, and pushing creates it. After a Docker Desktop
restart, the detail says the builder is not running, and pushing starts it back up. Either way,
push once, then run dip doctor again, and emulation reports ok or FAILED with real
evidence. Any other unknown detail, such as a failed or unreadable check of the builder, means
the check could not get a clear answer this time, and a push will not necessarily fix it.--json emits a stable, machine-readable document instead of the table. --offline skips every row
that needs the network: dip, workspace, registry, builder, push token and dbt. The other
rows still run, including session, which reads your cached login.
dip doctor is deliberately a fixed checklist, not a growing status page: the planes, engines,
metrics and business vocabulary your tenant owns are dip plane list, dip engine list,
dip semantic list and dip ontology list instead — see Command reference.
Connecting your coding agent
Every data plane runs its own MCP server for your tenant, and an agent connected to it can browse your query engines, search your metadata and read your metrics — always as you, or as whichever service user’s key it holds.dip login registers MCP servers after installing the agent skills. From a coding agent’s
terminal, it registers with that agent; --agent NAME chooses explicitly. From a plain terminal,
it adds absent entries in installed clients (Claude Code, Codex and Cursor), leaving every existing
entry untouched. For an entry that differs, it prints the exact replacement command for you to choose.
Use --no-mcp or set DIP_NO_MCP=1 (true or yes also works) to skip registration;
explicit --agent NAME or --mcp=true overrides the environment setting.
When it adds tools, it prints one summary naming the clients changed and each client’s next step.
For Claude Code, start a new conversation in the same folder and ask your question again. It never adds the Claude Code allow rule by default.
Adding Codex opens Codex’s own browser sign-in; if you do not finish it within two minutes, the
server stays registered and codex mcp login <name> finishes the sign-in later.
dip never edits a config file an agent owns:
Each server is registered under the name
dippr-<tenant>-<plane>; if two planes would reduce to
the same name, dip appends a short suffix so they stay distinct. An agent that is not installed on
your machine is skipped, and dip prints the exact command you would run once it is. For Codex, dip
looks on your PATH, then at the copy bundled inside ChatGPT.app on macOS (Contents/Resources/codex);
set DIP_CODEX_BIN to the executable’s path if yours is somewhere else. If Codex’s sign-in did not
finish (no browser, or you closed the tab), dip says so and names codex mcp login <name>, which
runs it again. A Codex registration an earlier dip made reads a 15-minute token from
ALTIMATE_API_KEY; dip replaces it with Codex’s own sign-in when that token is exported where it
runs, and otherwise leaves it (switch with codex mcp add <name> --url <url> (no bearer flag), approve the sign-in, and restart Codex). A server already
registered at the same URL with the same sign-in is left alone, which is what keeps a Claude Code
sign-in for it intact.
Signing in to the MCP server
Claude Code signs in with yourdip login: each time it connects, it runs the registered
dip mcp token --header-json command, which trades your login for a token for that one server and
prints it only to Claude Code. The command refuses any other tenant or server. Nothing is written
into Claude Code’s config but the command, and revoking your login ends the access. Pass
--mcp-auth oauth to use the browser sign-in in /mcp instead. Codex signs in with its own browser
sign-in when the server is registered and renews it itself. Cursor reads a token from the
ALTIMATE_API_KEY environment variable. The per-client steps, and what to do when a connection does not come up, are
on Connect an AI agent.
Letting Claude Code use the tools
Only when you pass--allow-rule, dip adds one allow rule per server, mcp__dippr-<tenant>-<plane>,
to permissions.allow in your Claude Code settings (~/.claude/settings.json, or
$CLAUDE_CONFIG_DIR/settings.json when you set that variable). Without the flag dip writes no rule
and says how to add one. Claude Code starts in auto mode, where it reviews each tool call on its own and
refuses Dippr’s SQL and column reads as sensitive data. The rule turns off Claude Code’s prompts for
every Dippr tool, including the tools that write and any tool added later, in every mode, not only
auto mode. Each call still runs as you, with nothing beyond your access. The run prints one line naming
the rule and the file. Only the allow list in the file changes. Pass --no-allow-rule to take a rule
dip added back out; see
Claude Code’s auto mode.
Use --dry-run on either command to see every command and file change it would make without running
any of them. The one exception: if your saved login is close enough to expiring that reading the
plane list has to refresh it, that refresh still happens, and the run says so when it does.
Related
Command reference
Every
dip command, its flags, and what each one needs.Using dip in CI
Building and pushing an app with an API key instead of a browser login.