The hub command¶

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

hub is installed in every IDE image. It talks to the hub'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 hub config (hub::deploy(), hub::apps(), hub::run(), …), so you can do the same from the R console.

hub deploy [DIR] [--name NAME] [--no-renviron] [--force]
hub apps
hub history NAME
hub rollback NAME [DIGEST]
hub delete NAME
hub owner NAME [USER]
hub init [DIR] [--type KIND] [--name NAME] [--force]
hub config get [KEY] | set KEY VALUE | unset KEY
hub sysreqs [DIR]
hub env list NAME | set NAME KEY=VALUE ... | unset NAME KEY ...
hub apikey NAME [--rotate]
hub mcp [--json]
hub run NAME
hub runs NAME
hub logs NAME [RUN]
hub git bind URL [--branch main] [--path DIR] [--name NAME]
                 [--user USER] [--token TOKEN]
hub git status NAME
hub git unbind NAME

Everyone on the hub can deploy and run hub apps and hub mcp. The person who deploys an app first owns it, and the hub refuses a deploy under a name that belongs to someone else. Only the owner of an app, its maintainers and hub 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 run a pipeline and list its runs and logs. Maintainers are the people and groups listed under maintainers and maintainer-groups in the app's hub.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¶

hub 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, hub.yaml holds the name, and a different --name is refused. --no-renviron leaves .Renviron and .env out of the app's secret for this deploy. --force builds even when nothing has changed.
hub apps: Lists every deployed app on the hub with its kind, owner, time of the last deploy and URL. For a pipeline, it shows the schedule instead of a URL. For an app bound to a repository, it also shows the repository.
hub history NAME: 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.
hub rollback NAME [DIGEST]: Makes new sessions start the build before the current one, or the build whose digest starts with DIGEST as hub 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 hub 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.
hub delete NAME: Removes the app, its images and its secret. For a pipeline, it also removes the store. Only the owner or an admin can delete an app.
hub 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 hub apps shows owners. Only the owner or an admin can hand an app over, and the hub refuses it while a deploy of the app runs. The maintainers stay as they are. If you want to keep working on the app, add yourself to maintainers and deploy before you hand it over. A pipeline's runs call APIs with the groups of the owner, and the pipelines under uses: must admit the owner. Until the new owner deploys the app, the hub counts no groups for them.
hub init [DIR] [--type KIND]: Writes a hub.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, …). hub::new_app() writes this file for you, and so does the first deploy of a directory that has none.
hub config get [KEY], hub config set KEY VALUE, hub config unset KEY: Reads or edits one key of hub.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. Because a removed key keeps its last value on the hub, hub config unset schedule writes schedule: "", which turns the timetable off.
hub 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 hub.yaml. Without a lock file, or if the lookup is turned off on your hub, the command says so and prints only the system-packages.

Secrets and environment¶

hub 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 hub env set.
hub env set NAME KEY=VALUE ...: Sets secret variables of a deployed app. They 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.
hub env unset NAME KEY ...: Removes variables from the app's secret, whether they came from a file or from hub env set.

On every deploy, the hub 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 hub env unset. Keys set with hub env set are left alone. Values under env: in hub.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¶

hub 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 hub 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.
hub mcp [--json]: Lists the deployed MCP servers you may use, with the name, the title, the address inside the hub and the public address. The hub registers these servers in your Claude Code and Posit Assistant at every session start. The session setup reads the --json output. It holds no keys, because a server on the hub knows you by your session.

Pipelines¶

hub run NAME: Starts a run of a pipeline 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 hub 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 hub run exits with status 1 because it cannot tell how the run ended. hub runs NAME then shows its state.
hub runs NAME: Lists the runs of a pipeline, newest first, with their state, whether they were started by hand or by the schedule, and their times.
hub logs NAME [RUN]: Prints the log of the last run, or of RUN as hub runs names it. Logs are kept for seven days. Of the runs that the schedule starts, the hub 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¶

hub git bind URL, hub git status NAME and hub 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.

From R¶

The hub package is available in every R session on the hub.

Function	Equivalent
`hub::deploy(dir = ".", name = NULL, renviron = TRUE, force = FALSE)`	`hub deploy`
`hub::apps()`, `hub::history(name)`, `hub::rollback(name, digest = NULL)`, `hub::delete(name)`, `hub::owner(name, user = NULL)`	The commands of the same name
`hub::init(dir, type, name)`, `hub::sysreqs(dir)`	`hub init --type --name`, `hub sysreqs`
`hub::env_list(app)`, `hub::env_set(app, KEY = "value")`, `hub::env_unset(app, "KEY")`	`hub env`
`hub::apikey(name, rotate = FALSE)`, `hub::mcp()`	`hub apikey`, `hub mcp`
`hub::run(name)`, `hub::runs(name)`, `hub::logs(name, run = NULL)`	The pipeline commands
`hub::git_bind(url, branch = "main", …)`, `hub::git_status(name)`, `hub::git_unbind(name)`	`hub git`
`hub::new_app(name, template = )`, `hub::templates()`	Creates a new project from a template
`hub::user(session)`, `hub::groups(session)`, `hub::in_group(group, session)`	Returns who is using the app or calling the API, and whether they are in a group (Kinds)
`hub::api_url(name)`	Returns the address of a deployed API inside the hub
`hub::store(name)`	Returns the path at which the app mounts a pipeline's store