Skip to content

The velonde command

This page is the reference for the velonde command, which you use in an IDE session to deploy and manage apps, APIs, MCP servers and pipelines.

velonde is installed in every IDE image. It talks to the workspace's deploy service, which identifies you by the session the command runs in, so you do not log in or configure anything. The R package has a function for every command except velonde config, velonde packages token and velonde mcp add|remove (velonde::deploy(), velonde::apps(), velonde::run(), …), so you can do most of it from the R console.

velonde new [NAME] [--template T] [--dir DIR] [--no-install] [--no-git] [--repo] [--json]
velonde deploy [DIR] [--name NAME] [--no-renviron] [--force]
           [--confirm-access] [--confirm-dir]
velonde apps [--json]
velonde show NAME [--json]
velonde history NAME [--json]
velonde rollback NAME [DIGEST]
velonde delete NAME [--yes]
velonde owner NAME [USER]
velonde init [DIR] [--type KIND] [--name NAME] [--force]
velonde config get [KEY] | set KEY VALUE | unset KEY [--dir DIR]
velonde sysreqs [DIR]
velonde ide-packages [list]
velonde ide-packages add [PKG ...] [--for RPKG ...] [--no-wait]
velonde ide-packages remove PKG ...
velonde env list NAME | set NAME KEY ... | unset NAME KEY ...
velonde apikey NAME [--rotate]
velonde mcp [--json]
velonde mcp add|remove NAME ...
velonde packages token [--revoke] [--days N]
velonde ui [--background] [--port N]
velonde run NAME
velonde runs NAME [--json]
velonde logs NAME [RUN] [--since 24h] [--lines 1000] [--follow]
velonde audit [--since 7d] [--user ID] [--app NAME] [--action ACTION]
          [--outcome ok|refused|failed] [--limit 200] [--json]
velonde git bind URL [--branch main] [--path DIR] [--name NAME]
                 [--user USER] [--token TOKEN] [--confirm-access]
velonde git status NAME
velonde git unbind NAME
velonde clone NAME|URL [DIR] [--no-restore]
velonde git login [URL] [--forge github|gitlab] [--check]
velonde git logout [URL]
velonde git create [DIR] [--name REPO] [--group GROUP]
                    [--visibility private|internal]

Everyone on the workspace can deploy and run velonde apps and velonde mcp. The person who deploys an app first owns it, and the workspace refuses a deploy under a name that belongs to someone else. Only the owner of an app, its maintainers and workspace admins can deploy, change or roll back the app. They are also the only ones who can see its history, its secret variables and the key of an API, and who can read its logs, run a pipeline and list its runs. Maintainers are the people and groups listed under maintainers and maintainer-groups in the app's velonde.yaml. Only the owner and admins can delete the app, change those two keys and hand the app to another owner. Work on an app as a team describes how to share an app.

Deploy and manage

velonde deploy [DIR]

Builds DIR (by default the current directory) and publishes it. The overview describes what happens during a deploy. --name sets the app name on the first deploy. After that, velonde.yaml holds the name, and a different --name is refused before anything is uploaded. The command refuses your home directory as DIR, and it never uploads .ssh, .config/velonde and other files that hold your credentials. A .velondeignore file in the directory names what else to leave out, see What is uploaded. --no-renviron leaves .Renviron and .env out of the app's secret for this deploy. --force builds even when nothing has changed.

A deploy that opens the app to more people asks first: one that makes it external or public, and one that removes its access lists. In a terminal, the command asks. Where it cannot ask, it stops before the upload and says what the deploy would open, and --confirm-access is the answer. The Deploy button in VS Code asks in a dialog.

The name in velonde.yaml alone says which app a deploy replaces, and a copy of a project carries that name along. The workspace therefore remembers the directory of your last deploy of an app. When you deploy the app from another directory, the command asks in the same way, and --confirm-dir is the answer. To deploy a copy as an app of its own, change name: in its velonde.yaml.

velonde check [DIR] [--no-tests]
Runs the checks of a deploy without deploying. The command uploads what velonde deploy would upload, the workspace checks it for secrets, known vulnerabilities and risky code, and nothing is built or changed. Then the command runs the tests step in your session: every R and Python file must parse, and the tests in tests/testthat and tests/ must pass. The tests run with the project's own packages, its renv library in R and its uv environment or requirements.txt in Python. A deploy runs them again in the build, where the result can differ if the project's packages differ from the lock file. --no-tests leaves the tests to the deploy. The command ends with a deploy would pass these checks or a deploy would stop at these checks, and exits with status 1 in the second case.
velonde apps [--json]
Lists the deployed apps that you may open, that you own or maintain, and the workspace's packages, each with its kind, owner, time of the last deploy and URL. Velonde admins see every app. For a pipeline, it shows the schedule instead of a URL, and for a package its newest version. For an app bound to a repository, it also shows the repository. With --json the command prints the list as JSON for a script to read. Each app then also has a role, which says what you are to it: owner, maintainer, admin or null. velonde history and velonde runs take --json in the same way.
velonde history NAME [--json]
Lists the last ten deploys and rollbacks of an app, newest first, with the digest, the time, who deployed it, and the commit and branch it was built from. New sessions start the build on the first line. A * after a commit means the deploy included uncommitted changes or files that git ignores, so what runs is not exactly that commit. by git marks a build from a bound repository. For a package, each line also shows the version it published.
velonde show NAME
Prints what the workspace holds for an app: every setting as the workspace has it now, where the app is reached, the last deploy, and whether it is up. For an API or MCP server that is how many of its pods are ready and whether one keeps restarting. For an app it is the number of containers running right now, which is zero while nobody has it open. For a pipeline or report it is the last run and when the schedule last started one. A key that velonde.yaml leaves out keeps its last value on the workspace, so this command, and not the file, shows what applies. The owner, maintainers and admins can run it.
velonde rollback NAME [DIGEST]
Makes new sessions start the build before the current one, or the build whose digest starts with DIGEST as velonde history lists it. Running sessions keep the build they started with. A rollback is listed in the history, but it does not count as a build, so each further velonde rollback goes one more build back. To return to a later build, give its digest. You can only restore builds that are still in the history. An API or MCP server restarts with the restored build, without failed requests. For an app with warm containers (prestart, or seats-per-container above one), the rollback restarts the apps server to replace them, which takes about a minute. A rollback changes the image only. The workspace refuses to roll back to a build from before the app changed its kind, for example from a Shiny app to a document. Deploy the earlier code again in that case. A package has no rollback, because every published version stays installable.
velonde delete NAME [--yes]
Removes the app, its images and its secret. For a pipeline, it also removes the store. A delete cannot be undone. In a terminal, the command asks you to type the name. Where there is no terminal to ask in, it needs --yes. For an R or Python package, it removes every version from the package repository, and NAME may be the package's own name. Only the owner or an admin can delete an app.
velonde packages token [--revoke] [--days N]
Creates a personal token for reading the workspace's package repository from outside the workspace, and prints the settings for R, pip and uv that use it. The token works for N days, by default and at most 365. A new token replaces your previous one. With --revoke, your token stops working.
velonde owner NAME [USER]
Without USER, shows the owner of the app and its maintainers. With USER, hands the app to that user id, written as velonde apps shows owners. Only the owner or an admin can hand an app over, and the workspace refuses it while a deploy of the app runs. The handover removes the app's maintainers and its repository binding: the new owner decides who else works on it. Until the new owner deploys the app, it keeps running the code deployed so far, but a pipeline's runs call APIs as nobody and the app mounts no pipeline stores under uses:. An API or MCP server gets a new key, which the new owner reads with velonde apikey. The app's secret variables stay with it, and the command lists them so that the new owner can replace them. From their deploy on, the runs call APIs with the new owner's groups, and the pipelines under uses: must admit them.
velonde new [NAME] [--template T] [--dir DIR] [--no-install] [--no-git] [--repo] [--json]
Creates a project from one of the workspace's templates in the directory NAME, or in DIR: the template's sources, a velonde.yaml, the project's CLAUDE.md on a workspace with AI assistants, and a git repository with a first commit (--no-git skips it). Inside an existing repository, the project gets none of its own and you commit it there. For an R template, which needs R and so RStudio or VS Code, it also creates an renv project with the template's packages. For a Python template, which needs uv, it writes uv.lock and installs the packages into the project's .venv, and for a notebook it registers a Jupyter kernel of that environment under the project's name. --no-install skips renv and uv. --repo then creates the project's repository on your git server, as velonde git create does. The default template is shiny where R is installed and shiny-python elsewhere; without NAME the command lists the templates, with --json as JSON. velonde::new_app() runs this command. See New projects.
velonde init [DIR] [--type KIND] [--name NAME] [--force]
Writes a velonde.yaml into DIR that sets name and title and lists every other key as a comment with its default. --type keeps only the keys that apply to that kind (shiny, plumber, quarto, targets, …). --name sets the app name, by default the directory's name. --force replaces a velonde.yaml that exists. velonde::new_app() writes this file for you, and so does the first deploy of a directory that has none.
velonde config get [KEY], velonde config set KEY VALUE, velonde config unset KEY
Reads or edits one key of velonde.yaml in the current directory, or in the directory given with --dir. Write nested keys with dots (env.LOG_LEVEL, resources.memory) and the values of list keys separated by commas (access-groups finance,sales). set and unset change only the lines of that key and leave the rest of the file as it is, comments included. set writes the value so that it reads back as you typed it, quoting it where YAML would read a number or a boolean. Keys under params take dots as well (params.region). Because the workspace keeps the last value of a key that velonde.yaml leaves out, unset writes such a key as null (audience: null, maintainers: null), and the next deploy removes the setting from the app, which then has the default again. Keys the workspace reads at every deploy, such as type or system-packages, are removed from the file.
velonde sysreqs [DIR]
Prints, as an apt-get install line, the apt packages the build will install for the renv.lock in DIR, plus any system-packages from velonde.yaml. Without a lock file, or if the lookup is turned off on your workspace, the command says so and prints only the system-packages.
velonde ui [--background] [--port N]
Serves the page that RStudio's addin "Velonde: deployed apps" shows in the Viewer: the list of deployed apps with logs, runs, history and rollback. You do not normally run it yourself, because the addin and velonde::page() start it. It listens on 127.0.0.1 inside your session only. With --background it starts once per session, prints its address and returns.

System libraries of the IDEs

velonde ide-packages [list]
Lists the system packages the workspace adds to the IDE images, and the state of each image: up to date with the packages it installs on top, being built, or the last lines of a build that failed. Anyone can run it.
velonde ide-packages add [PKG ...] [--for RPKG ...]
Adds Ubuntu packages to the three IDE images. --for takes R package names instead and adds the system libraries Posit Package Manager lists for them, so velonde ide-packages add --for sf adds what sf needs to load and to build from source. Packages the images have already are skipped. The command waits until the images are rebuilt, which takes a few minutes, and then new sessions have the packages. A session that is running keeps its image until you stop it and start it again. --no-wait returns at once. Only workspace admins can add or remove packages. If you are not an admin, the command prints the packages your images lack and the command to give to an admin.
velonde ide-packages remove PKG ...
Takes packages off the list, and the images are rebuilt without them.

Logs

velonde logs NAME [--since 24h] [--lines 1000] [--follow]

Prints what an app, document, API or MCP server wrote to its output: R's messages, warnings and errors, print() and cat() to the console, Python's prints and logging, and the web server's lines. --since says how far back, such as 30m, 2h or 7d, up to 30 days, and --lines how many of the most recent lines at most, up to 5000. The lines come in one block per container, with the time of each line. A Shiny app or document has a container per user unless it shares containers, so each block is one user's session or one shared container.

On a workspace with the monitoring stack, the workspace keeps every container's lines, so you also see containers that have already stopped, such as one that crashed while it started or a session that ended. Without the monitoring stack you see the containers that exist now, and of a container that restarted also its previous run. The output's first line says so.

With --follow (or -f), the command prints the last 20 lines and then goes on printing new lines as they come, until you press Ctrl+C or an hour has passed. The lines come from the workspace's log store, so they appear a few seconds after the app wrote them, and a workspace without the monitoring stack cannot follow an app.

Only the owner, the maintainers and admins can read the logs, because a log can contain the app's data. For a pipeline, velonde logs prints a run's log instead (see Pipelines).

velonde audit [--since 7d] [--user ID] [--app NAME] [--action ACTION] [--outcome ok|refused|failed] [--limit 200] [--json]
Prints the workspace's audit trail, newest first: who did what, to which app, when, and whether the workspace allowed it. Only workspace admins can read it. --since reaches back up to 365d, --user shows what one person did, --app what was done to one app, API, pipeline or package, and --action one kind of action, such as deploy, env.change or api.call. --outcome refused shows only what the workspace refused. --json prints the events with all their fields, for a script.

Secrets and environment

velonde env list NAME
Lists the secret variables of an app and where each one came from: the .Renviron or .env of the last deploy, or velonde env set.
velonde env set NAME KEY ...
Sets secret variables of a deployed app. In a terminal the command asks for each value. Otherwise it reads the values from standard input, one line per key, for example printf '%s\n' "$TOKEN" | velonde env set myapp API_TOKEN. KEY=VALUE on the command line works too, but other processes and your shell history can then read the value. In R, velonde::env_set("myapp", API_TOKEN = token) passes the values on standard input. The variables are kept across deploys and take precedence over a key of the same name in the file. New sessions of an app see the change, and running sessions keep their values. An API or MCP server restarts with the new values, without failed requests.
velonde env unset NAME KEY ...
Removes variables from the app's secret, whether they came from a file or from velonde env set.

On every deploy, the workspace replaces the keys that came from the previous .Renviron or .env with those of the new file (from both files if both exist). A deploy without either file, or with --no-renviron, keeps the keys of the last file. To remove them, use velonde env unset. Keys set with velonde env set are left alone. Values under env: in velonde.yaml are not secret: anyone who can read the app's settings sees them. Use them for settings such as a log level.

APIs and MCP servers

velonde apikey NAME [--rotate]
Prints the key of a deployed API or MCP server, together with its URL and a curl example. The key is for callers that have no identity, and the user name to send with it is api. Only the owner, the maintainers and workspace admins can see the key. --rotate replaces it, and existing callers must switch to the new one. Kinds explains when to use a key and when to use another way in.
velonde mcp [--json]
Lists the deployed MCP servers you may use, with the name, whether the workspace registers it for you, the title, the address inside the workspace and the public address. At every session start the workspace registers your own servers and those whose access-groups name one of your groups (auto) in your Claude Code and Posit Assistant, plus those you added (added). The --json output holds no keys, because a server on the workspace knows you by your session.
velonde mcp add|remove NAME ...
Registers a server you may use but that the workspace does not register by itself, typically one whose access-groups are empty (open to everyone), or stops registering one you added. Claude Code has the change at once, Posit Assistant at the next session start. A server's tool descriptions and results reach your assistant, so add servers of people you trust.

Pipelines and scheduled reports

velonde run NAME
Starts a run of a pipeline, or a render of a scheduled report, now and follows its log until it ends with run succeeded, run FAILED or run skipped. A pipeline runs once at a time, so the workspace refuses a second run while the first is still going. A run that starts anyway, such as a scheduled run while a manual one is going, does nothing and ends with skipped: another run of this pipeline is in progress. If the connection to the deploy service drops, the run goes on, and velonde run exits with status 1 because it cannot tell how the run ended. A skipped run exits with status 0. velonde runs NAME then shows its state.
velonde runs NAME [--json]
Lists the runs of a pipeline or the renders of a report, newest first, with their state, whether they were started by hand, by the schedule, by a deploy or after a pipeline, and their times.
velonde logs NAME [RUN] [--follow]
For a pipeline or a scheduled report, prints the log of the last run, or of RUN as velonde runs names it. With --follow, it prints the log of a run that is still going as the run writes it, and ends with the run. Logs are kept for seven days. Of the runs that the schedule starts, the workspace keeps at most the last ten that succeeded and the last ten that failed. Only the owner, the maintainers and admins can read the logs, because a log can contain the pipeline's data.

Repositories

velonde git bind URL, velonde git status NAME and velonde git unbind NAME bind an app to a branch, so that a push to that branch deploys it. They are described on a page of their own.

velonde clone NAME gets the code of a deployed app to work on it, velonde git login stores your token for your git server, and velonde git create creates a repository for a project. They are described in Working on an app's code together.

From R

The velonde package is available in every R session on the workspace.

Function Equivalent
velonde::deploy(dir = ".", name = NULL, renviron = TRUE, force = FALSE, confirm_access = FALSE, confirm_dir = FALSE) velonde deploy
velonde::deploy_check(dir = ".", tests = TRUE) velonde check. Returns TRUE when a deploy would pass the checks. The name avoids devtools::check()
velonde::deploy_job(dir = NULL) velonde deploy as a background job in RStudio, which is what the addin "Deploy to the workspace" runs
velonde::page() Opens the list of deployed apps with logs, history and rollback in RStudio's Viewer, which is what the addin "Velonde: deployed apps" runs
velonde::apps(), velonde::app(name) (for velonde show), velonde::history(name), velonde::rollback(name, digest = NULL), velonde::delete(name, ask = interactive()), velonde::owner(name, user = NULL) The commands of the same name
velonde::init(dir, type, name, force = FALSE), velonde::sysreqs(dir) velonde init --type --name --force, velonde sysreqs
velonde::ide_packages(), velonde::ide_packages_add(packages, r_packages, wait = TRUE), velonde::ide_packages_remove(packages) velonde ide-packages
velonde::env_list(app), velonde::env_set(app, KEY = "value"), velonde::env_unset(app, "KEY") velonde env
velonde::apikey(name, rotate = FALSE), velonde::mcp() velonde apikey, velonde mcp
velonde::logs(name, run = NULL, since = "24h", lines = NULL, follow = FALSE) velonde logs
velonde::run(name), velonde::runs(name) The pipeline commands
velonde::git_bind(url, branch = "main", …), velonde::git_status(name), velonde::git_unbind(name) velonde git
velonde::clone(name, dir = NULL, restore = TRUE, open = interactive()) velonde clone, and opens the project in RStudio
velonde::git_login(url = NULL), velonde::git_logout(url = NULL), velonde::git_create(dir = ".", name = NULL, group = NULL, visibility = "private") velonde git login, velonde git logout, velonde git create
velonde::new_app(name, template = , repo = FALSE), velonde::templates() Creates a new project from a template with velonde new, with repo = TRUE also its repository; lists the R templates. A Python template works as well
velonde::user(session), velonde::groups(session), velonde::in_group(group, session) Returns who is using the app or calling the API, and whether they are in a group (Kinds)
velonde::api_url(name) Returns the address of a deployed API inside the workspace
velonde::store(name) Returns the path at which the app mounts a pipeline's store