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.--namesets the app name on the first deploy. After that,velonde.yamlholds the name, and a different--nameis refused before anything is uploaded. The command refuses your home directory asDIR, and it never uploads.ssh,.config/velondeand other files that hold your credentials. A.velondeignorefile in the directory names what else to leave out, see What is uploaded.--no-renvironleaves.Renvironand.envout of the app's secret for this deploy.--forcebuilds even when nothing has changed.A deploy that opens the app to more people asks first: one that makes it
externalorpublic, 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-accessis the answer. The Deploy button in VS Code asks in a dialog.The name in
velonde.yamlalone 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-diris the answer. To deploy a copy as an app of its own, changename:in itsvelonde.yaml. velonde check [DIR] [--no-tests]- Runs the checks of a deploy without deploying. The
command uploads what
velonde deploywould 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 intests/testthatandtests/must pass. The tests run with the project's own packages, its renv library in R and itsuvenvironment orrequirements.txtin 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-testsleaves the tests to the deploy. The command ends witha deploy would pass these checksora 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
--jsonthe command prints the list as JSON for a script to read. Each app then also has arole, which says what you are to it:owner,maintainer,adminornull.velonde historyandvelonde runstake--jsonin 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 gitmarks 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.yamlleaves 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
DIGESTasvelonde historylists 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 furthervelonde rollbackgoes 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, orseats-per-containerabove 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, andNAMEmay 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
Ndays, 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. WithUSER, hands the app to that user id, written asvelonde appsshows 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 underuses:. An API or MCP server gets a new key, which the new owner reads withvelonde 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 underuses: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 inDIR: the template's sources, avelonde.yaml, the project'sCLAUDE.mdon a workspace with AI assistants, and a git repository with a first commit (--no-gitskips 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 writesuv.lockand 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-installskips renv and uv.--repothen creates the project's repository on your git server, asvelonde git createdoes. The default template isshinywhere R is installed andshiny-pythonelsewhere; withoutNAMEthe command lists the templates, with--jsonas JSON.velonde::new_app()runs this command. See New projects. velonde init [DIR] [--type KIND] [--name NAME] [--force]- Writes a
velonde.yamlintoDIRthat setsnameandtitleand lists every other key as a comment with its default.--typekeeps only the keys that apply to that kind (shiny,plumber,quarto,targets, …).--namesets the app name, by default the directory's name.--forcereplaces avelonde.yamlthat 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.yamlin 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).setandunsetchange only the lines of that key and leave the rest of the file as it is, comments included.setwrites the value so that it reads back as you typed it, quoting it where YAML would read a number or a boolean. Keys underparamstake dots as well (params.region). Because the workspace keeps the last value of a key thatvelonde.yamlleaves out,unsetwrites such a key asnull(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 astypeorsystem-packages, are removed from the file. velonde sysreqs [DIR]- Prints, as an
apt-get installline, the apt packages the build will install for therenv.lockinDIR, plus anysystem-packagesfromvelonde.yaml. Without a lock file, or if the lookup is turned off on your workspace, the command says so and prints only thesystem-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 on127.0.0.1inside your session only. With--backgroundit 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.
--fortakes R package names instead and adds the system libraries Posit Package Manager lists for them, sovelonde ide-packages add --for sfadds whatsfneeds 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-waitreturns 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()andcat()to the console, Python's prints and logging, and the web server's lines.--sincesays how far back, such as30m,2hor7d, up to 30 days, and--lineshow 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 logsprints 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.
--sincereaches back up to365d,--usershows what one person did,--appwhat was done to one app, API, pipeline or package, and--actionone kind of action, such asdeploy,env.changeorapi.call.--outcome refusedshows only what the workspace refused.--jsonprints 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
.Renvironor.envof the last deploy, orvelonde 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=VALUEon 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
curlexample. The key is for callers that have no identity, and the user name to send with it isapi. Only the owner, the maintainers and workspace admins can see the key.--rotatereplaces 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-groupsname one of your groups (auto) in your Claude Code and Posit Assistant, plus those you added (added). The--jsonoutput 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-groupsare 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 FAILEDorrun 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 withskipped: another run of this pipeline is in progress. If the connection to the deploy service drops, the run goes on, andvelonde runexits with status 1 because it cannot tell how the run ended. A skipped run exits with status 0.velonde runs NAMEthen 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
RUNasvelonde runsnames 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 |