Visivo v2.0.3: A Consistent CLI and Cloud API

Visivo v2.0.3 is a parity release. It makes the visivo CLI API consistent with Visivo Cloud, cleans up how deploy authorization works, and hardens the release build. The headline is boring in the best way: the thing you build locally now behaves the same when it runs in the cloud.

Most of this release happened below the surface. There is no new chart type to show off and no new model concept to learn. What changed is the contract between the local CLI and the hosted product, and that contract is the part that decides whether a workflow ports cleanly or falls apart the moment it leaves your laptop. This recap walks through what shipped and why API parity is worth a release on its own.

What shipped in v2.0.3

Three things landed in v2.0.3, and they are tightly related:

• A CLI API consistent with Visivo Cloud. The shapes the local CLI uses to describe a project, a deploy, and a run now match what Visivo Cloud expects. The same call that works against your machine works against the hosted endpoint.
• Deploy authorization cleanup. The path that authorizes a deploy was simplified and tightened so the rules are predictable and there are fewer places for a token or permission check to behave inconsistently.
• Release-build hardening. The build that produces the distributed CLI was made more robust, so the binary you install behaves the same across the platforms we ship.

None of these add surface area. They remove inconsistencies. That is the right kind of work for a patch release on the 2.0 line, where the goal is to make the foundation we committed to in 2.0 solid rather than to pile new features on top of it.

A CLI API consistent with Visivo Cloud

The core change in v2.0.3 is that the CLI and Visivo Cloud now speak the same API. Before this release, the local CLI and the hosted service had drifted in small ways. Each one had grown its own conventions, and a request shape that the CLI produced was not always exactly what the cloud expected, or the other way around. Individually these gaps were minor. Together they were the reason a project that ran cleanly on your machine could behave differently once deployed.

v2.0.3 closes that gap. The CLI now uses the same API contract as Visivo Cloud, so there is one definition of what a project, a run, and a deploy look like. The practical effect is that the mental model you build locally is the mental model that applies in the cloud. You do not relearn anything at the deploy boundary, because there is no second system with its own rules waiting on the other side.

This matters most for the everyday loop. You define a model, declare your metrics and dimensions, and describe what you want to see as an Insight:

# project.visivo.yml
name: revenue-overview

models:
  - name: orders
    sql: "SELECT * FROM orders"
    metrics:
      - name: net_revenue
        expression: "SUM(amount - refunds)"
    dimensions:
      - name: order_month
        expression: "DATE_TRUNC('month', created_at)"

insights:
  - name: monthly-revenue
    props:
      type: bar
      x: ?{ ${ref(orders).order_month} }
      y: ?{ ${ref(orders).net_revenue} }

That project compiles and runs the same way whether the CLI is talking to your local environment or to Visivo Cloud, because both ends now agree on what the project means. The semantic layer was always meant to be the single source of truth, and a consistent API is what lets that single source of truth travel from local to hosted without translation.

Deploy authorization cleanup

Deploying is the moment a local project becomes a shared, hosted thing, so it is exactly where authorization needs to be unambiguous. In v2.0.3 we cleaned up the deploy authorization path.

The old behavior worked, but the rules around who could deploy what, and how a token was checked, had accumulated edge cases. Cleaning that up means the authorization decision is now made in a consistent way, with fewer branches for a check to slip through differently than you expected. You run a deploy to a stage and the rules that govern it are the same rules every time:

visivo deploy -s production

The benefit is predictability. When authorization is consistent, a deploy that succeeds today succeeds for the same reasons tomorrow, and a deploy that is denied is denied for a reason you can actually point at. For teams treating their dashboards as code and shipping them through pull requests, that predictability is the difference between a deploy step you trust and one you babysit.

Release-build hardening

The third piece is the build that produces the CLI we distribute. v2.0.3 hardened that release build.

Visivo ships as an installable CLI across multiple platforms, and the build pipeline that produces those artifacts is itself software that can drift or break. Hardening it means the produced binary is more reliably the same thing, install after install and platform after platform. You install Visivo with the standard path and get a CLI that behaves the way the release notes say it does:

pip install --upgrade visivo
# or, with the install script:
curl -fsSL https://visivo.sh | bash

This is unglamorous infrastructure work, and that is the point. A consistent API is only worth as much as the binary that implements it. Hardening the release build is what makes the parity in v2.0.3 something you can actually rely on rather than something that is true only on the machine where it was tested.

Why API parity matters

It is fair to ask why a release would spend its whole budget making two systems agree instead of adding something new. The answer is that parity is the feature.

The promise of a tool that runs both locally and in the cloud is that you get the best of both: fast, private iteration on your machine, and sharing, scheduling, and scale in the hosted product. That promise only holds if the two environments behave the same. The instant they diverge, you are debugging the gap between them instead of doing analytics, and "it works on my machine" becomes a real and expensive problem.

By making the CLI API consistent with Visivo Cloud, v2.0.3 removes that class of problem at the source. A project that runs locally runs in the cloud. A deploy that is authorized locally is authorized the same way in the cloud. The same config produces the same results in both places, so moving from local development to a hosted deployment is a change of environment, not a change of behavior.

That is the whole bet of BI-as-code: your dashboards are defined in files you can version, review, and run anywhere. v2.0.3 makes "anywhere" mean what it says.

If you want to try the local-to-cloud loop yourself, /get-started walks you from pip install to your first Insight in a few minutes, and you can create a hosted project at app.visivo.io to deploy it. The migration and deploy details live in the documentation.

Previously in Visivo

v2.0.3 builds directly on the previous patch. For the changes that came just before this parity work, read the v2.0.2 release recap. And to follow the releases as they ship, subscribe below. The next recap lands when the next version does.