Command-line tool (kv)

Install

curl -fsSL https://cloud.knovadigital.com/cli/install.sh | sh

It installs kv in ~/.local/bin/kv . If your shell doesn't find it afterwards, add ~/.local/bin to your PATH .

For every user of the computer, curl -fsSL https://cloud.knovadigital.com/cli/install.sh | sh -s -- --system installs it in /usr/local/bin (with sudo).

The installer checks the downloaded file against its SHA-256 ( https://cloud.knovadigital.com/cli/kv.sha256 , also shown on your Profile ) and stops if it doesn't match.

Prefer to read the script before running it? Download it, read it, then run it:

curl -fsSLo install.sh https://cloud.knovadigital.com/cli/install.sh

less install.sh

sh install.sh

Windows: download https://cloud.knovadigital.com/cli/kv and run it with Python, e.g. python kv login , python kv projects .

kv update replaces kv with the latest version, after checking its SHA-256 the same way. kv --version prints the version you have.

Sign in

Run kv login It prints a code such as ABCD-EFGH and a link, opens your browser on it, and waits up to 10 minutes.

Check and approve in the browser Sign in to Cloud Buddy if you aren't. The page shows the device's name, the address and client that asked, and the scopes it wants. Check the code matches your terminal, uncheck the scopes it doesn't need, pick when its token expires (30, 90 or 365 days) and click Approve . Like creating a token, approving needs a sign-in from the last 30 minutes and, with two-factor on, a code from your authenticator app.

Back in the terminal kv receives its token and is ready. kv whoami shows the account and token it uses.

Only approve a code you asked for Approve only if you just ran kv login yourself. Never approve a code someone sent you (by email, chat or phone): whoever holds the terminal gets a token that acts as you. Click Deny instead.

--scope read,builds:write,backups:write,admin : the scopes to ask for. The default is read,builds:write .

--name "Work laptop" : the device name shown on the approval page and in the token's name.

--url https://… : the platform's address, to sign in to another platform (see profiles ).

--no-browser : only print the link (on a server, or over SSH): open it on any device where you are signed in.

kv login --scope read,builds:write,backups:write --name "Work laptop"

The token is a personal access token: it is listed in Profile → Access tokens , where you can revoke it. kv keeps it in ~/.config/kv/config.json , readable only by you ( 0600 ), or %APPDATA%\kv\config.json on Windows.

kv logout removes the token from that file and, when it was created by kv login , revokes it. A token you gave with --token is only forgotten locally: revoke it from your Profile. kv logout --keep-token forgets a kv login token without revoking it.

CI and servers: an access token

Without a browser, create a token in Profile → Access tokens with the scopes the job needs, then either save it with kv login --token (it reads the token from its input, or asks for it without showing it), or set it in the KV_TOKEN environment variable with the platform's address in KV_URL : nothing is saved then.

echo "$KV_TOKEN" | kv login --token

# or, without saving anything

export KV_URL=https://cloud.knovadigital.com

export KV_TOKEN=kvp_…

kv projects

A GitHub Actions job that rebuilds staging and follows the build (store the token as the repository secret KV_TOKEN ):

.github/workflows/rebuild-staging.yml

name: Rebuild staging

on:

workflow_dispatch:

jobs:

rebuild:

runs-on: ubuntu-latest

steps:

- name: Install kv

run: curl -fsSL https://cloud.knovadigital.com/cli/install.sh | sh

- name: Rebuild staging and wait for it

env:

KV_URL: https://cloud.knovadigital.com

KV_TOKEN: ${{ secrets.KV_TOKEN }}

run: ~/.local/bin/kv build my-project/staging --wait

Several platforms or accounts: profiles

Each profile has its own address and token. Add --profile NAME to any command, or set KV_PROFILE for the whole shell. kv whoami (or kv env ) shows the platform address, the profile, your account, the token's name, prefix, scopes and expiry, and where the configuration file is.

kv login --profile client-a --url https://cloud.client-a.com

kv projects --profile client-a

export KV_PROFILE=client-a

kv whoami

Projects, branches and status

kv projects : your projects.

kv branches <project> : a project's branches.

kv status [project[/branch]] : the state of a project or a branch. Inside a git checkout, kv finds the project from the git remote and the branch from the one checked out, so kv status alone is enough.

A project can be given by its slug, name or id, a branch by its name or id: acme/staging , 12/34 . The global flags --project and --branch do the same.

Builds and logs

kv build <project>/<branch> : rebuild the branch (scope builds:write ). --wait follows the build's log until it finishes.

kv logs <project>/<branch> : the last build's log. --build N picks another build, --file another log ( build , odoo.log , install , tests …), -f keeps following it.

kv explain <project>/<branch> : the AI explanation of a failed build: what broke and how to fix it. --build N for another build, --again for a new explanation.

kv build acme/staging --wait

kv logs acme/staging --file odoo.log -f

kv explain acme/feature-invoices

Open, connect and shell

kv open [project/branch] : opens the branch's address in your browser.

kv connect [project/branch] : opens Odoo signed in, as the administrator or as --login <user> . It needs the admin scope.

kv shell [project/branch] : a shell in the running build over SSH ( ssh -p <port> <build>@<ssh host> ), with the SSH key registered on your Profile . --print only prints the command.

Your role on the stage still applies: developers reach development branches, testers staging too, admins production as well.

Backups and database downloads

kv backups <project> : the project's backups.

kv backup <project> : make a backup of production now, or of a staging branch with --branch <staging-branch> (scope backups:write ).

kv db download <project>/<branch> : download the branch's database (scope backups:write ). -o file chooses where, --no-filestore leaves the filestore out.

kv backup acme

kv db download acme/main -o acme.zip

Your account, tokens and servers

kv whoami (alias kv env ): who you are, on which platform, with which token.

kv tokens : the token kv is using. The full list is in Profile → Access tokens : managing tokens needs a dashboard session.

kv servers : your linked servers (platform admins: --owner platform|customers|mine|<user id> ). kv installs : the Odoo installs on them. Both need a token that isn't limited to some projects.

kv update : update kv ( --check only says whether a new version is available). kv --version : its version. kv help : the list of commands.

Global flags and environment variables

These work with every command, before or after it:

--json : machine-readable output, e.g. kv projects --json | jq .

--project , --branch : the project and the branch, instead of project/branch .

--profile NAME : the profile to use (or KV_PROFILE ).

--no-color : plain output, also with the NO_COLOR environment variable.

-v , --verbose : debug output, with the HTTP requests kv makes (the token is never printed).

Environment variables: KV_TOKEN (a token to use), KV_URL (the platform's address), KV_PROFILE and NO_COLOR .

Exit codes and permissions

0 : done. 1 : an error. 2 : wrong usage (a missing argument, an unknown flag).

3 : authentication or permission (the API answered 401 or 403). The message says which scope is missing: sign in again with it, e.g. kv login --scope read,backups:write .

4 : not found (a project, branch or build).

The scopes are those of access tokens : read , builds:write , backups:write and admin . Whatever its scopes, a token never has more rights than your role on each project.