The Divvent command line

The Divvent command line lets you do from a terminal what the API does: list your applications, ask for a change, read the proposal, approve it, release it, roll it back and export the model. Every command it offers for your account starts with divvent cloud, and each one is a single call to the API, made as you. It can never do more than your role in the portal allows. See The Divvent API.

Installing it

The command line isn't yet available to install outside Divvent: it isn't published anywhere a customer can download it from. Until it is, everything below can be done with the API directly, from any language or build system.

The rest of this article describes how it works, so you know what to expect when it is available.

Sign in

divvent cloud login

It prints a link and a code:

Open https://app.divvent.co.uk/device?code=BCDF-GHJK
and check the code there is BCDF-GHJK. Approve it, signed in.

Open the link. The portal's Sign in a terminal page has the code filled in: check it matches, and press Continue. The page then shows the program asking and every scope it asked for. If you started this yourself, just now, press Approve; otherwise press Deny. Approving needs a sign-in from the last five minutes, so the portal may ask for your passkey or authenticator app again. The code lasts ten minutes.

The terminal then finishes on its own. The token it receives lasts thirty days, is never printed, and is kept in your computer's own secure store:

By default, a terminal asks for applications:read, requests:write, deploys:trial and export:read: enough to read, ask for changes, release to test copies and export. Ask for more when you need it:

divvent cloud login --scopes applications:read,changes:approve,deploys:production

The scopes are the API's. See The Divvent API.

divvent cloud whoami says who you are signed in as, what the token may do and when it expires. divvent cloud logout revokes the token and forgets it on this computer.

Look around

divvent cloud apps
divvent cloud app <application>
divvent cloud requests <application>
divvent cloud deploys <application>

<application> is the id divvent cloud apps shows. Add --json to any command for output a script can read.

Ask for a change, and approve it

divvent cloud ask <application> "Add a nickname to customers"
divvent cloud thread <application> <request>
divvent cloud reply <application> <request> "Only for business customers"
divvent cloud proposal <application> <request>
divvent cloud approve <application> <request>

A change that only adds, or keeps everything working as it was, is approved there and then, if your role may approve it. A breaking or destructive change needs you, signed in now: the command prints a link instead, and the change waits until you open it and press Approve this change in the portal. Add --wait to have the terminal wait for you.

divvent cloud decline <application> <request> --reason "…" declines a change, and divvent cloud withdraw withdraws one.

Release, promote and roll back

divvent cloud deploy <application> --trial try-nickname --open --wait
divvent cloud promote <application> --trial try-nickname --wait
divvent cloud rollback <application> --wait
divvent cloud rollback <application> --restore
divvent cloud deploy-status <application> <deploy>

Name a test copy with --trial, and add --open to open it if it isn't there yet. Without --trial, the release goes to your live application, which needs the deploys:production scope and a role that may release there (an admin or an owner). promote puts exactly what a test copy runs on the live application. rollback goes back one release; --restore puts the data back to where it was too. divvent cloud cancel withdraws a release nobody has started.

See Release a version, Try a version in a test copy and Roll back a release for what each of these does.

Export

divvent cloud export <application> --out my-application.json

The file is your application's current model, whole, with its version history. Your data is not part of it: use the Export page in the portal for that. See Export your application and your data.

In a build job

Make a token in the portal with only the scopes the job needs (see The Divvent API), keep it in the build system's secret store, and give it to the job as DIVVENT_API_TOKEN:

- run: divvent cloud deploy ${{ vars.APPLICATION }} --trial ci --open --wait
  env:
    DIVVENT_API_TOKEN: ${{ secrets.DIVVENT_API_TOKEN }}

When that variable is set, it is used before the stored token.

Never put a token on the command line. The command line refuses one given as an option, or anywhere else on the line. By then it is in your shell's history, so revoke it on the portal's API tokens and webhooks page and make another.