arv is the command-line client for Arvados. With arv, you can access Arvados API and Keep services, view and operate on Arvados resources and objects, and perform admin work. It is distributed as part of the Arvados Python SDK.
You can start using your Arvados cluster with arv after configuring the working environment with an Arvados API token. Please refer to the sections ‘Getting an API token’ and ‘Checking your environment’ in the User Guide for details. In this document, we will use zzzzz to stand for the Arvados cluster ID.
arv is a collection of subcommands that can be broadly divided into three kinds, namely, high-level resource subcommands, data subcommands, and low-level resource subcommands that closely follow the Arvados API semantics.
For every subcommand, you can get help with the -h/--help option. For example, arv collection update -h will print the help information about the specific subcommand collection update.
Exit codes: arv exits with 0 on success, with 2 when the command-line input is invalid, and with 1 on all other errors.
arv get — Fetch Arvados objectsUsage: arv [--format=json|yaml] get UUID [FIELDS ...]
arv get retrieves an Arvados object by its UUID and writes it to the standard output as JSON (default) or YAML.
The optional FIELDS arguments can be specified to select the fields in the object to display.
Example: Display collection, limiting output to uuid, portable_data_hash, version, and modified_at fields.
$ arv get zzzzz-4zz18-12345abcde67890 uuid portable_data_hash version modified_at
{
"uuid": "zzzzz-4zz18-12345abcde67890",
"portable_data_hash": "1361eacc54cd808e2377d30a742cc9d2+53",
"version": 3,
"modified_at": "2025-01-23T12:34:56.789012000Z"
}
arv create — Create Arvados objects in your editorUsage: arv [--format=json|yaml] create RESOURCE [--project-uuid=UUID]
arv lets you interactively create new Arvados objects. The editor program to run is determined by environment variables: VISUAL is used if it is set; otherwise, EDITOR is used. If neither VISUAL nor EDITOR is set, arv uses nano if it is available in PATH, and falls back to vi otherwise.
arv create starts a text editor in which you can create a new Arvados object using one of the two supported formats, JSON (default) or YAML. The RESOURCE argument can be any of the supported Arvados resource types (e.g., collection, group, user, etc.) as detailed in the API Reference.
When you save the work in the editor and exit, arv will validate the object, then send an API request for object creation. If a problem arises, detailed error messages will be shown, and you will see a prompt like the following:
Edit and try again? ([Y]es/no)
You can then choose to edit the object again until the problem is fixed, or discard the object at any time. Saving an empty file or object will also stop the editing process.
Options:
| Option | Description | Notes |
|---|---|---|
--project-uuid=UUID |
Place the newly-created object in the specified project if appropriate. |
arv edit — Update Arvados objects in your editorUsage: arv [--format=json|yaml] edit UUID [FIELDS ...]
Similar to arv create, arv edit lets you update an existing Arvados object using a text editor.
Just like with arv get, you can optionally select the fields of the object to be shown in the editor. However, you are not limited to those fields, because you can always add any (valid) fields in the editor. Conversely, removing any fields from the object means that those fields will not be updated.
The editing process largely follows that of arv create. If any problem arises after you save the object and exit the editor, you will be interactively prompted to fix it, before the changes are actually committed to Arvados.
The following subcommands work on data associated with Arvados objects.
arv copy — Move objects across Arvados clustersarv copy is an alias of the arv-copy command. It can copy collections, projects, and workflows (with their dependencies) from one Arvados cluster to another, or download data from URLs to Arvados collections. More examples can be found in the section ‘Using arv-copy’ of the User Guide, and you can refer to the output of arv copy --help for more about the command-line parameters.
arv keep ls — List Arvados collection contentsUsage: arv keep ls [-s] LOCATOR
arv keep ls lists the file contents of Arvados collections.
The LOCATOR can be either a collection UUID (in the form of zzzzz-4zz18-12345abcde67890) or a portable data hash (PDH).
Selected options:
| Option | Description | Notes |
|---|---|---|
-s |
Show file sizes in KiB. |
Example: List files in collection by portable data hash.
$ arv keep ls -s 9178fe1b80a08a422dbe02adfd439764+925
1 ./README.txt
53877 ./raw_fastq/Irrel_kd_1.subset.fq
46349 ./raw_fastq/Irrel_kd_2.subset.fq
35419 ./raw_fastq/Irrel_kd_3.subset.fq
73933 ./raw_fastq/Mov10_oe_1.subset.fq
67068 ./raw_fastq/Mov10_oe_2.subset.fq
41741 ./raw_fastq/Mov10_oe_3.subset.fq
10555 ./reference_data/chr1-hg19_genes.gtf
248277 ./reference_data/chr1.fa
arv keep get — Copy data from Keep or fetch collection manifestUsage: arv keep get [options] LOCATOR[PATH] [DEST]
arv keep get copies data from Keep to a local destination DEST, or fetches collection manifests. This subcommand is an alias of arv-get.
The LOCATOR argument can be one of the following:
LOCATOR type |
Description | Notes |
|---|---|---|
| Collection UUID or portable data hash | Fetch the collection’s manifest text. | |
Collection UUID or portable data hash, with PATH |
Download file(s) in the collection. | A PATH starts with the slash (/) character and refers to a file or directory in the collection. A directory path (one ending in a /) refers to its contents recursively. A single / as the PATH refers to the full contents of the collection. |
| Keep locator with token signature | Download the individual data block in Keep. |
The DEST argument specifies the location where the output is downloaded. By default, the output is written to the standard output. However, when recursively downloading a directory, the destination must be a local directory path.
Selected options:
| Option | Description | Notes |
|---|---|---|
-f |
Overwrite existing files at DEST. |
Default: refuse to write anything if any of the output files already exist. |
--skip-existing |
Skip files that already exist at DEST when downloading by path. |
|
--hash=ALGORITHM |
Output file digest by the specified hash algorithm when downloading by path. | Available algorithms: md5, sha1, sha224, sha256, sha384, and sha512. |
--strip-manifest |
Remove token signatures from the manifest output. |
Example: Write file content from Keep to standard output.
$ arv keep get zzzzz-4zz18-12345abcde67890/hello.txt
hello, world
Example: Download whole collection to current directory and compute file digests.
$ arv keep get --hash sha256 --no-progress 1361eacc54cd808e2377d30a742cc9d2+53/ . 2> SHA256SUM $ sha256sum -c SHA256SUM ./hello.txt: OK
Example: Fetch collection manifest, with token signatures.
$ arv keep get zzzzz-4zz18-12345abcde67890
. 22c3683b094136c3398391ae71b20f04+13+Aa611e1b3689f1af04bc46f7ba226d03dade48845@6a49fa07 0:13:hello.txt
With --strip-manifest, token signatures are not shown in the manifest output:
$ arv keep get --strip-manifest zzzzz-4zz18-12345abcde67890
. 22c3683b094136c3398391ae71b20f04+13 0:13:hello.txt
Example: Download single block by Keep locator (as shown in the manifest output of the preceding example).
$ arv keep get 22c3683b094136c3398391ae71b20f04+13+Aa611e1b3689f1af04bc46f7ba226d03dade48845@6a49fa07 block $ cat block hello, world
More examples, including federated downloads, can be found in the User Guide section ‘Downloading data’.
arv keep put — Upload data to KeepUsage: arv keep put [OPTIONS] [PATHS ...]
arv keep put uploads data to Keep. In the most common usage, the PATHS are uploaded to Keep and a collection is created with those files as its contents. Alternatively, an existing collection can be updated with new local files.
If a path argument is a local directory with a trailing slash (/), the contents under the directory will be uploaded. Otherwise, the directory itself will be a level in the collection.
This subcommand is an alias of arv-put. More examples can be found in the section ‘Uploading data’ of the User Guide.
Selected options:
| Option | Description | Notes |
|---|---|---|
--name |
Set the collection name. | |
--exclude=PATTERN |
Exclude files by glob pattern. | Can be given multiple times. |
--update-collection=UUID |
Update the existing collection identified by the UUID with new file uploads. | |
--storage-classes |
Specify the desired storage classes by a comma-separated list. | |
--normalize |
Perform manifest normalization after writing data. |
Example: Update the ‘hello-world’ collection.
In this example, the collection is downloaded to the current directory, a new file hola.txt is added, and the collection is updated with it.
$ arv keep get zzzzz-4zz18-12345abcde67890 . 0 MiB / 0 MiB 100.0% $ ls hello.txt $ echo 'hola, mundo' > hola.txt $ arv keep put --update-collection zzzzz-4zz18-12345abcde67890 ./ 2026-06-22 10:06:14 arvados.arv_put[7354] INFO: Calculating upload size, this could take some time... 2026-06-22 10:06:14 arvados.arv_put[7354] INFO: Creating new cache file at /home/user/.cache/arvados/arv-put/2a9792e8c4d207bd70cf7470c85c3bbc 0M / 0M 100.0% 2026-06-22 10:06:15 arvados.arv_put[7354] INFO: Collection updated: 'hello-world' zzzzz-4zz18-12345abcde67890
The file that already exists in the collection, hello.txt, is skipped by arv keep put when we upload the current directory’s contents.
arv keep putWith the option --stream, arv keep put uploads the files to Keep, but does not create a collection. Instead, the manifest text is written to the standard output.
With the option --raw, files are uploaded to Keep, and the comma-separated list of locators of the resulting data blocks is written to the standard output.
arv keep docker — List or upload Docker imagesUsage: arv keep docker [OPTIONS] [IMAGE[:TAG]]
When invoked as arv keep docker, the command displays the Docker images stored on the Arvados cluster.
When the IMAGE argument is given, optionally with a tag (default tag: latest), the command uploads the Docker image to Arvados. Upon completion, the UUID of the collection containing the image is written to the standard output.
arv keep docker is an alias of the arv-keepdocker command. Further examples can be found in the section ‘Working with container images’ in the User Guide.
Selected options:
| Option | Description | Notes |
|---|---|---|
--project-uuid=UUID |
Upload the Docker image to the project specified by UUID. | |
--name |
Set the collection’s name for the upload. | |
--pull |
Pull the Docker image from an image registry. | Default: only upload local images (--no-pull). |
Example: Pull image and upload to Arvados.
The following command pulls the image with a specific tag from the BioContainers registry and uploads it to Arvados.
$ arv keep docker --pull quay.io/biocontainers/star:2.7.5c--0
[...]
2026-06-24 23:55:13 arvados.arv_put[7557] INFO: Collection saved as 'Docker image quay.io biocontainers star:2.7.5c--0 sha256:89936'
zzzzz-4zz18-veebf08kyoi9eks
arv has a collection of subcommands that closely follow the semantics of the Arvados API service.
The basic usage pattern of these API resource subcommands is as follows:
arv [--format=json|yaml|uuid] RESOURCE METHOD [PARAMETERS]
RESOURCE is one of the resource types to operate on, for example, collection, user, container_request, etc. Notice that the argument typically takes the singular noun form: “group” as opposed to “groups”.
METHOD refers to the operation, for example, create, list, update, delete, etc. Methods shared by most resources are described in ‘Common resource methods’ in the API documentation. In addition, many resources support additional methods, as detailed in their respective sections in the API documentation. For instance, the user resource has activate, setup, merge methods, etc.
PARAMETERS are arguments taken by a method, and they are documented in the API Reference under each resource-method combination.
foo_bar becomes the command-line parameter --foo-bar. For example, for arv collection update, the replace_files API argument becomes --replace-files.foo becomes a pair of CLI parameters --foo and --no-foo, for true and false values respectively. For example, the API method argument ensure_unique_name becomes the pair --[no-]ensure-unique-name. Currently, all boolean parameters are optional and default to false.-c), except the “negated” forms of boolean parameters like --no-ensure-unique-name. Please check the output of arv resource method -h for the short parameters of a specific resource-method combination.The CLI bindings for the resources, methods, and parameters are defined by the discovery document published by the Arvados API server. A comprehensive list of available resources for your Arvados cluster can be viewed by running arv --help.
The following command-line options to arv control the output format.
| Option | Description | Notes |
|---|---|---|
--format=json |
Output as JSON (default). | |
--format=yaml |
Output as YAML. | |
--format=uuid, -s, or --short |
Only output object UUID(s). | For the list method, output the individual items’ UUIDs, one line each. |
The create and update methods both take a ‘resource-type’ parameter. This simply refers to a parameter named after the resource itself.
The value of a resource-type parameter can be one of the following:
{ });-), which causes the input value to be read from the standard input.(In the rare case where the file path string itself happens to be valid JSON, an error is reported.)
Examples:
$ arv collection update --collection=[...]
and
$ arv api_client_authorization create --api-client-authorization=[...]
both show the respective resource-type parameters on the command line.
Example: Get collection from federated cluster by portable data hash.
For collections, the get method provides for a special use case of fetching a collection by its portable data hash. If the portable data hash is not found on the home cluster, federated clusters are searched. When getting a collection by the portable data hash, only the kind, manifest_text, portable_data_hash, and trash_at fields are populated with meaningful values.
$ arv collection get --uuid 133e9a1bcd7899d51aa8a2b6b6f9fea9+61 --select '[
"kind", "manifest_text", "portable_data_hash", "trash_at"
]'
{
"kind": "arvados#collection",
"manifest_text": ". deb944805bc57a3010079a8ecf1eb48d+1339378+Rzzyzx-7ab32fdcc9cc588fb934196ff6162acdb9c353ec@6a4e5acd 0:1339378:user.jpg\n",
"portable_data_hash": "133e9a1bcd7899d51aa8a2b6b6f9fea9+61",
"trash_at": null
}
Example: Create new project.
$ arv group create --group '{"group_class": "project", "name": "hello-project"}'
{
"can_manage": true,
"can_write": true,
"created_at": "2026-06-24T07:39:20.950807457Z",
"delete_at": null,
"description": null,
"etag": "12345abcde67890fghij12345",
"frozen_by_uuid": null,
"group_class": "project",
"is_trashed": false,
"kind": "arvados#group",
"modified_at": "2026-06-24T07:39:20.946873000Z",
"modified_by_user_uuid": "zzzzz-tpzed-12345abcde67890",
"name": "hello-project",
"owner_uuid": "zzzzz-tpzed-12345abcde67890",
"properties": {},
"trash_at": null,
"uuid": "zzzzz-j7d0g-12345abcde67890",
"writable_by": [
"zzzzz-tpzed-12345abcde67890",
"zzzzz-tpzed-12345abcde67890"
]
}
Notice that here the --group option is a resource-type parameter.
Example: List users with email-address filter.
The list methods support the parameter --filters that can efficiently query the API service for objects matching specific conditions. The following command searches for users whose associated email addresses are in the specified domain, and outputs their UUIDs:
$ arv -s user list --filters '[["email", "ilike", "%@example.com"]]'
zzzzz-tpzed-12345abcde67890
More examples of using filters can be found in the API Reference.
You can also pass the path of a JSON file to the --filters parameter. Alternatively, a single dash (-) means reading the filters from the standard input.
Example: Update collection with --replace-files.
The ‘hello-world’ collection in a previous example contains two files, hello.txt and hola.txt at the top level.
We will add a new file hello-world.c to the collection, and re-organize the collection contents into two new directories: natural-languages that will contain the two existing files, and programming-languages with the new file.
The replace_files API argument lets us re-organize the collection contents with the collection update method.
First, we need to upload the new file content to Keep storage without creating a new collection, using the command arv keep put --stream. The manifest text is then written to the standard output:
$ arv keep put --stream hello-world.c
[...]
. bbae5d9983ce453e09ff5b2d40cca5c5+66+A225a7c0842f7fefbaedf42ed87cbcdb27cae836a@6a4e0c74 0:66:hello-world.c
Then, we perform an atomic update of collection contents:
$ arv collection update --uuid zzzzz-4zz18-12345abcde67890 --replace-files '{ > "/natural-languages/hello.txt": "current/hello.txt", > "/natural-languages/hola.txt": "current/hola.txt", > "/hello.txt": "", > "/hola.txt": "", > "/programming-languages/hello-world.c": "manifest_text/hello-world.c" > }' --collection '{ > "manifest_text": ". bbae5d9983ce453e09ff5b2d40cca5c5+66+A225a7c0842f7fefbaedf42ed87cbcdb27cae836a@6a4e0c74 0:66:hello-world.c\n" > }'
Example: Trashing collection.
$ arv collection delete --uuid zzzzz-4zz18-12345abcde67890
This puts the collection in the trash.
Examples about performing user administration work with arv can be found in the Admin Guide.
The following subcommands are grouped with the API resource commands.
arv config — Get Arvados cluster configurationUsage: arv [--format=json|yaml] config get
Get the publicly exported configuration of the Arvados cluster.
arv sys — Run data trash and sweepUsage: arv sys get
Run scheduled data trash and sweep operations across the cluster’s Keep services.
Note that for compatibility reasons, sy is an alias of the sys resource.
arv vocabulary — Get metadata vocabularyUsage: arv [--format=json|yaml] vocabulary get
Fetch the metadata vocabulary managed and exported by the Arvados cluster.
arv ws — WebSocket clientUsage: arv ws [OPTIONS]
arv ws provides access to the WebSocket event stream, displaying Arvados log events as they arrive. For detailed information about the logs API, please refer to its API Reference section.
Once started, this subcommand will keep listening to events until interrupted, for example, by Ctrl-C.
Selected options:
| Option | Description | Notes |
|---|---|---|
-f, --filters |
Apply filters to log events. | |
--uuid |
Filter by the object_uuid field of events. |
|
-i, --id=N |
Start from given log ID. | |
-s, --start-time=TIME |
Start from given time. | Format: YYYY-MM-DD or YYYY-MM-DD hh:mm:ss. |
Example:
The following session logs an event for collection trashing (slightly re-formatted for legibility).
$ arv ws
{
"event_at": "2026-06-25T02:12:21.650905Z",
"event_type": "update",
"id": 240,
"msgID": 2,
"object_kind": "arvados#collection",
"object_owner_uuid": "zzzzz-tpzed-12345abcde67890",
"object_uuid": "zzzzz-4zz18-12345abcde67890",
"properties": {
"new_attributes": {
"is_trashed": true,
"name": "hello-world",
"owner_uuid": "zzzzz-tpzed-12345abcde67890",
"portable_data_hash": "0c139c33f961ef83eb17508fb4255019+165"
},
"old_attributes": {
"is_trashed": false,
"name": "hello-world",
"owner_uuid": "zzzzz-tpzed-12345abcde67890",
"portable_data_hash": "0c139c33f961ef83eb17508fb4255019+165"
}
},
"uuid": "zzzzz-57u5n-qwj78wid4oohho1"
}
The content of this documentation is licensed under the
Creative
Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the
Apache License, Version 2.0.