Record and File Operations
Records are a core concept in the coScene platform. This document lists common operations for records and their files, with simple examples.
For detailed parameters of specific commands, use cocli [command] [subcommand] -h to view them. This document only lists commonly used commands, parameters, and usage.
cocli record -h
Work with coScene record.
Usage:
cocli record [command]
Available Commands:
copy Copy a record to target project
create Create a new record
delete Delete a record
describe Describe record metadata
download Download all files from a record
file Manage files in records
list List records in a project
moment Manage moments in records
move Move a record to target project
update Update record metadata
upload Upload files or directory to a record
view View record details
Flags:
-h, --help help for record
Global Flags:
--config string config file path (default "/Users/yujing/.cocli.yaml")
--log-level string log level, one of: trace|debug|info|warn|error (default "info")
Use "cocli record [command] --help" for more information about a command.
Record Operations
Create a Record
cocli record create -t humanoid-episode-01 -d "the first episode of data collection"
Record created successfully!
-------------------------------------------------------------
Field Value
ID: c5f7a2fa-a366-41e0-b1d8-1498b75348f0
Name: projects/b3d9cb59-aeff-4448-aded-808b27608675/records/c5f7a2fa-a366-41e0-b1d8-1498b75348f0
Title: humanoid-episode-01
Description: the first episode of data collection
Create Time: 2025-07-17T21:56:07+08:00
Update Time: 2025-07-17T21:56:07+08:00
Archived: false
URL: https://portal.coscene.io/coscene-lark/docs/records/c5f7a2fa-a366-41e0-b1d8-1498b75348f0
-------------------------------------------------------------
When creating a record, you can set custom fields with --custom in key=value form (repeat as needed):
cocli record create -t my-record --custom "priority=high" --custom "batch=2025-03"
List Records in a Project
cocli record list
ID TITLE LABELS CREATE TIME
9c9177f6-8194-4d69-8536-3cfebce6fc23 humanoid-episode-200 2025-07-17T21:59:04+08:00
c729f6ab-f4e8-4d1e-adf4-24d0165939e9 humanoid-episode-199 2025-07-17T21:59:04+08:00
5ac02141-1ac9-4b5b-b0d0-6ea8df6bfcf4 humanoid-episode-198 2025-07-17T21:59:04+08:00
ab1eab19-6f46-422a-bb54-24157e7f24b3 humanoid-episode-197 2025-07-17T21:59:04+08:00
fe67cd75-6422-44cc-bd80-17a51c1f86a7 humanoid-episode-196 2025-07-17T21:59:03+08:00
44bb67cb-db4f-4aa8-9ef7-7354870a8b65 humanoid-episode-195 2025-07-17T21:59:03+08:00
c58469bd-6373-42cd-9bf0-e0e69adc440b humanoid-episode-194 2025-07-17T21:59:03+08:00
f1f6a93e-0d00-4c88-aadb-3483366fb864 humanoid-episode-193 2025-07-17T21:59:03+08:00
662464e6-9acd-4228-908b-013a714f8491 humanoid-episode-192 2025-07-17T21:59:03+08:00
72c569d8-20ba-4810-9db7-7fb6b9e928db humanoid-episode-191 2025-07-17T21:59:02+08:00
7a338e0c-619a-4b9d-8dca-c6486c6da4af humanoid-episode-190 2025-07-17T21:59:02+08:00
47f3b154-dfee-4a64-aaba-b869545fb18e humanoid-episode-189 2025-07-17T21:59:02+08:00
6b4e938c-eaa0-4e6f-9d12-d1ab79679e22 humanoid-episode-188 2025-07-17T21:59:02+08:00
ed3c6fdf-9fe9-4ebe-af4f-fb2f761a27f5 humanoid-episode-187 2025-07-17T21:59:02+08:00
d00077d9-65f6-4b30-a92a-61a6ec1e478e humanoid-episode-186 2025-07-17T21:59:01+08:00
fcd65058-d777-48ca-99f3-606fc02834e6 humanoid-episode-185 2025-07-17T21:59:01+08:00
53ffbdfa-43ae-44bf-abcd-a99548175776 humanoid-episode-184 2025-07-17T21:59:01+08:00
...
Next page available. To continue, add: --page-token "TOKEN_HERE"
The list command will display records in the project, showing 100 records per page by default. You can use pagination options to browse all records:
# Use page-token for pagination (recommended)
cocli record list --page-size 10 --page-token "TOKEN_FROM_PREVIOUS_RESPONSE"
# Or use --all to get all records
cocli record list --all
You can also use filter options to filter records:
# Filter by labels
cocli record list --labels "label1,label2"
# Filter by title keywords
cocli record list --keywords "keyword1,keyword2"
# Include archived records
cocli record list --include-archive
Use -o to choose the output format: besides the default table, wide, csv, json, and yaml are supported. For wide and csv, creator and user-type custom fields are resolved to readable names when the corresponding user information is accessible.
Pagination and export: wide, csv, json, and yaml behave like the table view and only include the current page by default (server-side pagination; when --page-size is omitted, up to 100 rows per page is typical). To export all records matching the current filters in one go, add --all (for very large result sets this may take longer; you can also use --page-token pagination as above and merge in a script). --labels, --keywords, and other filters can be used together with --all to mean all rows that match the filters.
# Wide table (more columns at a glance)
cocli record list -o wide
# Export current page to CSV (this page only)
cocli record list -o csv > records-page.csv
# Export all matching records to CSV (typical full export)
cocli record list --all -o csv > records-all.csv
Use -s / --search to pass a JSON Logic query string consistent with the web UI’s advanced search for more complex filtering. Note: --search cannot be used together with --include-archive, --labels, or --keywords. Choose one combination.
# Use single quotes around the JSON filter copied from the web UI
cocli record list --search '<search_json>'
# Example
cocli record list --search '{"and":[{"==":[{"var":"isArchived"},"false"]},{"and":[{"in":[{"var":"relatedLabels.id"},["29fd2ca8-edc6-433a-8cb7-94b1b340102d"]]},{">=":[{"var":"byteSize"},104857600]},{">=":[{"var":"summary.filesDuration"},0]}]}]}'
Upload Files to a Record
You can upload one or more local paths (files or directories) to a record. Directory uploads recurse into subdirectories by default; no extra flag is required. List multiple paths after the record ID or resource name, e.g. cocli record upload <record> ./a.mcap ./more-data/.
# Create a temporary file
touch episode-1.mcap
# Upload the file to the previously created Record
cocli record upload 9c9177f6-8194-4d69-8536-3cfebce6fc23 ./episode-1.mcap
-------------------------------------------------------------
Uploading files to record: 9c9177f6-8194-4d69-8536-3cfebce6fc23
Upload Status:
/Users/yujing/Workspace/co/docs/episode-1.mcap: Upload completed
Total: 1, Skipped: 0, Success: 1
View record at: https://portal.coscene.io/coscene-lark/docs/records/9c9177f6-8194-4d69-8536-3cfebce6fc23
In an interactive terminal, in-progress uploads show a progress bar (filled with =) and may show transfer rate and elapsed time; for environments without a TUI, see --no-tty and related flags in cocli record upload -h.
Download Files from a Record
cocli record download 9c9177f6-8194-4d69-8536-3cfebce6fc23 .
-------------------------------------------------------------
Downloading record 9c9177f6-8194-4d69-8536-3cfebce6fc23
View record at: https://portal.coscene.io/coscene-lark/docs/records/9c9177f6-8194-4d69-8536-3cfebce6fc23
Saving to /Users/yujing/Workspace/co/docs/9c9177f6-8194-4d69-8536-3cfebce6fc23
Downloading #1 file: episode-1.mcap
Download completed!
All 1 / 1 files are saved to /Users/yujing/Workspace/co/docs/9c9177f6-8194-4d69-8536-3cfebce6fc23
The CLI tool will package all files in the record into a folder named after the record ID. This feature helps maintain the independence of files when you need to download multiple records, making them easier to manage.
Delete a Record
The CLI tool can also be used to delete records. Deleting a record is a very dangerous operation, so please manually confirm whether you really need to delete the record or use the -f flag to force delete.
cocli record delete 9c9177f6-8194-4d69-8536-3cfebce6fc23
Are you sure you want to delete the record? (y/n) y
Record successfully deleted.
View Record Information
The CLI tool can use the describe or view command to view detailed information about a record. The describe command outputs detailed information about the record, while the view command outputs the URL of the record.
cocli record describe 52c5afac-22ca-4ab5-b9cf-fc069053b1af
Field Value
ID: 52c5afac-22ca-4ab5-b9cf-fc069053b1af
Name: projects/b3d9cb59-aeff-4448-aded-808b27608675/records/52c5afac-22ca-4ab5-b9cf-fc069053b1af
Title: humanoid-episode-100
Description: episode #100 of data collection
Create Time: 2025-07-17T21:58:43+08:00
Update Time: 2025-07-17T21:58:43+08:00
Archived: false
URL: https://portal.coscene.io/coscene-lark/docs/records/52c5afac-22ca-4ab5-b9cf-fc069053b1af
If the record is associated with a device or contains custom field values, this information will also be displayed in the describe command output. For describe, -o supports table, json, and yaml.
cocli record view 52c5afac-22ca-4ab5-b9cf-fc069053b1af
The record url is: https://portal.coscene.io/coscene-lark/docs/records/52c5afac-22ca-4ab5-b9cf-fc069053b1af
cocli record describe 52c5afac-22ca-4ab5-b9cf-fc069053b1af
Field Value
ID: 52c5afac-22ca-4ab5-b9cf-fc069053b1af
...
URL: https://portal.coscene.io/coscene-lark/docs/records/52c5afac-22ca-4ab5-b9cf-fc069053b1af
Update Record Information
The CLI also supports changing the record's name, description, labels, and custom fields. See the command help for the full flag list. Custom fields use --custom key=value and may be repeated.
cocli record update 52c5afac-22ca-4ab5-b9cf-fc069053b1af -d "Object movement process, mechanical arm torque did not reach expected level, failed" # Update record description
Successfully updated record projects/b3d9cb59-aeff-4448-aded-808b27608675/records/52c5afac-22ca-4ab5-b9cf-fc069053b1af
Managing Moments
Moments are an important concept in records, representing a point in time or an event within a record. Through the CLI tool, we can manage moments in records.
Create a Moment
cocli record moment create bcdcb5f5-0246-4416-b9a4-4b1df7aa48c6 -n "first trigger" -D 120 -T 1753271704
INFO created moment: projects/b3d9cb59-aeff-4448-aded-808b27608675/events/17a9c804-6306-4da2-ab77-7765fac7023d
INFO upserted task: projects/b3d9cb59-aeff-4448-aded-808b27608675/tasks/5a650b42-8cf8-4583-a419-82d9b063c65f
List Moments
View the list of moments in a record:
cocli record moment list bcdcb5f5-0246-4416-b9a4-4b1df7aa48c6
NAME TRIGGER TIME DURATION
first trigger 2025-07-23T19:55:04+08:00 2m0s
intersection 2025-07-21T19:55:04+08:00 1m30s
traffic light 2025-07-20T19:55:04+08:00 1m15s
For processing moment data in scripts, you can use JSON format output:
cocli record moment list bcdcb5f5-0246-4416-b9a4-4b1df7aa48c6 -o json
{
"events": [
{
"name": "projects/b3d9cb59-aeff-4448-aded-808b27608675/events/17a9c804-6306-4da2-ab77-7765fac7023d",
"displayName": "first trigger",
"triggerTime": "2025-07-23T11:55:04Z",
"createTime": "2025-07-23T11:55:25.600Z",
"updateTime": "2025-07-23T11:55:25.600Z",
"duration": "120s",
"device": {},
"task": {},
"creator": "users/883c8529-1c1a-403b-960d-71eff4699aa3",
"record": "projects/b3d9cb59-aeff-4448-aded-808b27608675/records/bcdcb5f5-0246-4416-b9a4-4b1df7aa48c6",
"rule": {}
}
],
"totalSize": "1"
}
Download Moment Data
Download moment data as a moments.json file to a local directory:
# Download to a specified directory (creates a subfolder named after the record-id)
cocli record moment download bcdcb5f5-0246-4416-b9a4-4b1df7aa48c6 ./output
# Download directly to the current directory (without creating a subfolder)
cocli record moment download bcdcb5f5-0246-4416-b9a4-4b1df7aa48c6 . --flat
Managing Record Labels
Labels are an important means of managing and querying records. By adding and removing labels from records, we can easily distinguish different data during batch processing and automation.
In a single record update, only one of --append-labels, --update-labels, or --delete-labels may be used (mutually exclusive). The sections below are separate examples.
Add Labels
cocli record update 52c5afac-22ca-4ab5-b9cf-fc069053b1af --append-labels "end-effector,wheels"
Successfully updated record projects/b3d9cb59-aeff-4448-aded-808b27608675/records/52c5afac-22ca-4ab5-b9cf-fc069053b1af
Delete Labels
cocli record update 52c5afac-22ca-4ab5-b9cf-fc069053b1af --delete-labels "end-effector"
Successfully updated record projects/b3d9cb59-aeff-4448-aded-808b27608675/records/52c5afac-22ca-4ab5-b9cf-fc069053b1af
Replace All Labels
cocli record update 52c5afac-22ca-4ab5-b9cf-fc069053b1af --update-labels "end-effector,pick-and-place"
Successfully updated record projects/b3d9cb59-aeff-4448-aded-808b27608675/records/52c5afac-22ca-4ab5-b9cf-fc069053b1af
Finally, let's confirm that the record's labels have been updated.
cocli record describe 52c5afac-22ca-4ab5-b9cf-fc069053b1af
Field Value
ID: 52c5afac-22ca-4ab5-b9cf-fc069053b1af
Name: projects/b3d9cb59-aeff-4448-aded-808b27608675/records/52c5afac-22ca-4ab5-b9cf-fc069053b1af
Title: humanoid-episode-100
Description: Object movement process, mechanical arm torque did not reach expected level, failed
Labels: pick-and-place, end-effector
Create Time: 2025-07-17T21:58:43+08:00
Update Time: 2025-07-18T15:21:07+08:00
Archived: false
URL: https://portal.coscene.io/coscene-lark/docs/records/52c5afac-22ca-4ab5-b9cf-fc069053b1af
File Operations
The CLI tool provides rich file management features, including listing, deleting, copying, and moving files.
List Files
cocli record file list 52c5afac-22ca-4ab5-b9cf-fc069053b1af
FILENAME SIZE UPDATE TIME CREATE TIME
episode-1.bag 500.6 MB 2025-07-18T15:25:25+08:00 2025-07-18T15:25:25+08:00
metadata.json 626 kB 2025-07-18T15:25:20+08:00 2025-07-18T15:25:20+08:00
map.png 174 kB 2025-07-18T15:25:16+08:00 2025-07-18T15:25:16+08:00
node-logs.log 522 kB 2025-07-18T15:25:12+08:00 2025-07-18T15:25:12+08:00
You can also use additional options to filter and view files:
# Recursively list all files (including subdirectories)
cocli record file list 52c5afac-22ca-4ab5-b9cf-fc069053b1af -R
# List files in a specific directory
cocli record file list 52c5afac-22ca-4ab5-b9cf-fc069053b1af --dir "logs/"
# Use JSON format output (for script processing)
cocli record file list 52c5afac-22ca-4ab5-b9cf-fc069053b1af -o json
Delete Files
cocli record file delete 52c5afac-22ca-4ab5-b9cf-fc069053b1af node-logs.log
Are you sure you want to delete the file 'node-logs.log' from record? (y/n) y
File 'node-logs.log' successfully deleted.
Copy Files
You can copy a file from one record to another:
cocli record file copy <source-record-id> <target-record-id> <filename>
Move Files
You can also move a file from one record to another:
cocli record file move <source-record-id> <target-record-id> <filename>