Drive Toolbox Scripting Guide

Generated: 2026-03-11 20:59:43 UTC

Scripts are used for two reasons: (a) to create custom reports and (b) to automate the many actions you can perform in Drive Toolbox.

Scripts are powerful. Use Dry Run to preview changes before running.

Examples:

• Select files and delete, move, or change sharing settings
• Create a report listing everyone you share files with
• Create a dashboard document that organizes files by Label, and contains a link to each file with that label

Users can utilize an integrated LLM to help write scripts.

Your First Script

// Count your files
let total = count(filter("is:file"));
log("You have " + total.to_string() + " files");

// Find large files
let big = files(filter("size:gt:50MB"), sort_order("size desc"), 10);
log("Top 10 largest files:");
for f in big {
    log("  " + f.name + " (" + f.size.to_string() + " bytes)");
}

Running Scripts

Desktop App: Open the Scripts page from the sidebar. Write or load a script, then click Run. Use the Dry-Run toggle to preview changes safely before executing. You can pass variables to scripts using the Variables panel.

The Reference tab provides a comprehensive and readily-accessible listing of Drive Toolbox-specific scripting language features. More general features of the scripting language we use, Rhai, can be found at https://rhai.rs/book.

Dry-Run Mode

Always test scripts with dry-run first. In dry-run mode:

• Queries run normally (you see real file counts and names)
• Mutations (actions that would actually change your files) are previewed but NOT executed
• You get a report showing exactly what would happen

Working with Files

Querying Files

Use filter() to create a search expression and files() to execute it:

// Basic queries
let all_folders = files(filter("is:folder"));
let pdfs = files(filter("name:ends_with:.pdf"));
let big = files(filter("size:gt:10MB"));

// With sorting and limits
let newest = files(filter("is:file"), sort_order("modified_time desc"), 20);
let largest = files(filter("is:file"), sort_order("size desc"), 10);

// Count without loading
let n = count(filter("recently:modified:7d"));
log("Modified this week: " + n.to_string());

See the Filter docs for details on how to write a filter; or use the LLM or Visual Filter Builder to help write the filter you need.

File Properties

Every file returned by files() is a DtFile object with these properties:

let f = files(filter("name:contains:report"))[0];

log(f.name);           // "Q1 Report.xlsx"
log(f.id);             // Google Drive file ID
log(f.size.to_string()); // Size in bytes
log(f.mime_type);      // MIME type
log(f.is_folder.to_string());
log(f.owned_by_me.to_string());
log(f.starred.to_string());
log(f.can_delete.to_string());

Helper Functions

let my_files = files(filter("is:file"));

// Extract IDs or names
let all_ids = ids(my_files);
let all_names = names(my_files);

// Look up a specific file
let specific = get_file("1abc123");

Common Tasks

Organizing with Labels

Personal labels are local to your account and instant:

let label = personal_label("needs-review");

// Find unlabeled files modified recently
let recent = files(filter("recently:modified:3d"));
let count = add_personal_label(recent, label);
log("Labeled " + count.to_string() + " files for review");

// Later, remove the label from completed files
let reviewed = files(filter("label:needs-review AND label:done"));
remove_personal_label(reviewed, personal_label("needs-review"));

Cleaning Up Storage

// Find large old files
let old_big = files(
    filter("size:gt:50MB AND modified_time:before:6mo AND owned_by_me:equals:true"),
    sort_order("size desc")
);

log("Found " + old_big.len().to_string() + " large old files:");
for f in old_big {
    log("  " + f.name + " - " + f.size.to_string() + " bytes");
}

// Delete to trash (can be recovered)
delete(old_big);

Managing Permissions

// Share documents with a team member
let docs = files(filter("name:contains:report AND is:file"));
share(docs, "colleague@company.com", "reader");

// Remove sharing from sensitive files
let sensitive = files(filter("label:confidential AND is_shared:equals:true"));
make_private(sensitive);

// Make documentation public
let public_docs = files(filter("label:public-docs"));
make_public(public_docs);

Moving and Renaming

// Move old files to archive
let archive_id = args["archive_folder"];
let old = files(filter("modified_time:before:1y AND is:file"));
move_to(old, archive_id);

// Create a new folder
create_folder("root-folder", "2026 Archive");

// Rename a specific file
let f = get_file(args["file_id"]);
rename(f, "New Name.docx");

Workspace Admin

For Google Workspace administrators:

// List all workspace users
let users = workspace_users();
log("Total users: " + users.len().to_string());

// Find suspended accounts
let suspended = workspace_users(#{ suspended: true });
for u in suspended {
    log(u.email + " - " + u.full_name + " (suspended)");
}

// Browse organizational structure
let orgs = workspace_org_units();
for org in orgs {
    log(org["path"] + " - " + org["name"]);
}

Using Variables

Scripts can receive variables from the caller via the args map:

// Access variables
let target = args["folder_id"];
let email = args.get("email");  // Returns () if not set

// Use defaults
let limit = if args.get("limit") == () { 100 } else { args["limit"].parse_int() };

Error Handling

// Try-catch for error handling
try {
    let f = get_file("invalid-id");
} catch(err) {
    log("Error: " + err.to_string());
}

Building Reports

Scripts can produce structured reports — table reports for data grids, or text reports for rich documents with headings, paragraphs, lists, embedded tables, and inline formatting. Text content supports full markdown including links, bold, italic, code, and inline HTML.

Table Reports

let table = report_table_new();
report_table_title(table, "Storage Usage Report");
report_table_column(table, "File Name");
report_table_column_aligned(table, "Size (bytes)", "right");
report_table_column(table, "Type");

let big = files(filter("size:gt:10MB"), sort_order("size desc"), 50);
for f in big {
    report_table_add_row(table, [f.name, f.size.to_string(), f.mime_type]);
}

report_set_table(table);
log("Report generated with " + big.len().to_string() + " files");

Text Reports with Embedded Tables

For richer documents with headings, paragraphs, and embedded tables:

let doc = report_text_new();
report_text_title(doc, "Drive Audit Report");

report_text_heading(doc, 2, "Summary");
let total = count(filter("is:file"));
let shared_count = count(filter("is_shared:equals:true"));
report_text_key_value(doc, (), [
    ["Total files", total.to_string()],
    ["Shared files", shared_count.to_string()],
]);

report_text_heading(doc, 2, "Large Files");
report_text_paragraph(doc, "Files over 50MB that may need attention:");

let table = report_table_new();
report_table_column(table, "Name");
report_table_column_aligned(table, "Size", "right");
let big = files(filter("size:gt:50MB"), sort_order("size desc"), 20);
for f in big {
    report_table_add_row(table, [f.name, f.size.to_string()]);
}
report_text_embed_table(doc, table);

report_set_text(doc);

Markdown Formatting Helpers

Use md_bold(), md_italic(), md_code(), and md_link() to compose formatted text inside paragraphs and list items. Use report_text_md() to insert raw markdown for advanced formatting (blockquotes, sublists, inline HTML).

let doc = report_text_new();
report_text_title(doc, "Formatted Report");

// Inline formatting in paragraphs
report_text_paragraph(doc, "Found " + md_bold("3 issues") + " that need review.");
report_text_paragraph(doc, "Status: " + md_italic("pending") + " — run " + md_code("sync --force") + " to fix.");

// Links in bullet lists
let items = [];
let my_files = files(filter("size:gt:50MB"), sort_order("size desc"), 3);
for f in my_files {
    items.push(md_link(f.name, "https://drive.google.com/file/d/" + f.id) + " (" + md_bold(f.size.to_string() + " bytes") + ")");
}
report_text_heading(doc, 2, "Large Files");
report_text_bullet_list(doc, items);

// Raw markdown for advanced formatting
report_text_md(doc, "> **Note:** Review these files before archiving.\n\n");

report_set_text(doc);

Reference

Read-Only Verbs

These verbs query data without modifying anything:

Function	Parameters	Returns	Description
filter	expression: String	DtFilter	Validates the expression using the core filter parser and returns a DtFilter
sort_order	expression: String	DtSortOrder	Validates the sort expression and returns a DtSortOrder
personal_label	name: String	DtPersonalLabel	Validates the label name and returns a DtPersonalLabel
shared_label	name: String	DtSharedLabel	Validates the label name and returns a DtSharedLabel
files	filter: DtFilter	Array<DtFile>	Return all files matching the filter
files	filter: DtFilter, sort: DtSortOrder	Array<DtFile>	Return filtered files in the specified sort order
files	filter: DtFilter, sort: DtSortOrder, limit: INT	Array<DtFile>	Return filtered, sorted files up to the limit
count	filter: DtFilter	INT	Return the number of matching files
get_file	file_id: String	DtFile	Return the file, or error if not found
all_personal_labels	(none)	Array<String>	Return all personal label names
personal_file_labels	file_id: String	Array<String>	Return personal label names for this file
all_shared_labels	(none)	Array<String>	Return all shared label names
shared_file_labels	file_id: String	Array<String>	Return shared label names for this file
all_personal_info_fields	(none)	Array<Map>	Return all personal info fields as maps with: name, field_type
personal_file_info	file_id: String	Array<Map>	Return personal info values as maps with: name, field_type, value
all_shared_info_fields	(none)	Array<Map>	Return all shared info fields as maps with: group, field
shared_file_info	file_id: String	Array<Map>	Return shared info values as maps with: group, field, value
workspace_users	(none)	Array<WsUser>	Return all workspace users (up to 1000)
workspace_users	options: Map	Array<WsUser>	Return filtered workspace users
workspace_org_units	(none)	Array<Map>	Return org units as maps with: path, name, parent_path, description
log	message: String	()	Appends the message to script output
ids	files: Array<DtFile>	Array<String>	Return array of file ID strings
names	files: Array<DtFile>	Array<String>	Return array of file name strings
report_table_new	(none)	INT	Create a new table builder, returns handle
report_table_title	handle: INT, title: String	()	Set table title
report_table_column	handle: INT, header: String	()	Add a column with default (left) alignment
report_table_column_aligned	handle: INT, header: String, align: String	()	Add a column with specified alignment
report_table_add_row	handle: INT, cells: Array	()	Add a data row
report_set_table	handle: INT	()	Set table as the script's report output
report_text_new	(none)	INT	Create a new text document builder, returns handle
report_text_title	handle: INT, title: String	()	Set document title
report_text_heading	handle: INT, level: INT, text: String	()	Add heading (level 1-6)
report_text_paragraph	handle: INT, text: String	()	Add paragraph
report_text_bullet_list	handle: INT, items: Array	()	Add bullet list
report_text_numbered_list	handle: INT, items: Array	()	Add numbered list
report_text_horizontal_rule	handle: INT	()	Add horizontal rule
report_text_md	handle: INT, markdown: String	()	Append raw markdown (for blockquotes, sublists, inline HTML, etc.)
md_link	title: String, url: String	String	Returns title with proper escaping
md_bold	text: String	String	Returns text
md_italic	text: String	String	Returns text
md_code	text: String	String	Returns text
report_text_key_value	handle: INT, title: Dynamic, entries: Array	()	Add key-value summary (title can be () for no title)
report_text_embed_table	text_handle: INT, table_handle: INT	()	Embed a table in the text document
report_set_text	handle: INT	()	Set text document as the script's report output

Mutation Verbs

These verbs modify data. They require confirmation and are intercepted by dry-run mode:

Function	Parameters	Returns	Description
delete	files: Array<DtFile>	String	Move files to trash. Returns action ID.
delete	file: DtFile	String	Move a single file to trash. Returns action ID.
delete	files: Array<DtFile>, options: Map	String	Delete files with options. permanent: true for permanent deletion. shared_file_handling controls behavior for files you don't own (default "skip").
delete	file: DtFile, options: Map	String	Delete a single file with options.
download	files: Array<DtFile>, destination: String	String	Queue download of files. Returns action ID.
download	file: DtFile, destination: String	String	Queue download of a single file. Returns action ID.
download	files: Array<DtFile>, destination: String, options: Map	String	Queue download with options. maintain_structure preserves folder hierarchy (default false). flatten is the inverse of maintain_structure. export_google_docs converts Google Docs to Office formats (default true). overwrite controls file overwrite behavior (default "skip").
download	file: DtFile, destination: String, options: Map	String	Queue download of a single file with options.
share	files: Array<DtFile>, email: String, role: String	String	Share files with the user. Returns action ID.
share	file: DtFile, email: String, role: String	String	Share a single file with the user. Returns action ID.
unshare	files: Array<DtFile>, email: String	String	Remove user's access. Returns action ID.
unshare	file: DtFile, email: String	String	Remove user's access from a single file. Returns action ID.
make_public	files: Array<DtFile>	String	Set public read access. Returns action ID.
make_public	file: DtFile	String	Set public read access on a single file. Returns action ID.
make_private	files: Array<DtFile>	String	Remove all sharing. Returns action ID.
make_private	file: DtFile	String	Remove all sharing from a single file. Returns action ID.
make_restricted	files: Array<DtFile>	String	Remove public access. Returns action ID.
make_restricted	file: DtFile	String	Remove public access from a single file. Returns action ID.
move_to	files: Array<DtFile>, folder_id: String	String	Move files to the folder. Returns action ID.
move_to	file: DtFile, folder_id: String	String	Move a single file to the folder. Returns action ID.
move_to	files: Array<DtFile>, folder_id: String, options: Map	String	Move files with options. flatten: true removes folder hierarchy, placing all files directly in the destination (default false).
move_to	file: DtFile, folder_id: String, options: Map	String	Move a single file with options.
rename	file: DtFile, new_name: String	String	Rename the file. Returns action ID.
create_folder	parent_id: String, name: String	String	Create a folder. Returns action ID.
add_personal_label	files: Array<DtFile>, label: DtPersonalLabel	INT	Add personal label. Returns count of files modified.
add_personal_label	file: DtFile, label: DtPersonalLabel	INT	Add personal label to a single file. Returns count of files modified.
remove_personal_label	files: Array<DtFile>, label: DtPersonalLabel	INT	Remove personal label. Returns count of files modified.
remove_personal_label	file: DtFile, label: DtPersonalLabel	INT	Remove personal label from a single file. Returns count of files modified.
clear_personal_labels	files: Array<DtFile>	INT	Clear all personal labels. Returns count of files modified.
clear_personal_labels	file: DtFile	INT	Clear all personal labels from a single file. Returns count of files modified.
add_shared_label	files: Array<DtFile>, labels: Array	String	Add shared labels. Returns action ID.
add_shared_label	file: DtFile, labels: Array	String	Add shared labels to a single file. Returns action ID.
remove_shared_label	files: Array<DtFile>, labels: Array	String	Remove shared labels. Returns action ID.
remove_shared_label	file: DtFile, labels: Array	String	Remove shared labels from a single file. Returns action ID.
set_shared_info	files: Array<DtFile>, group: String, field: String, value: String	String	Set shared info field. Returns action ID.
set_shared_info	file: DtFile, group: String, field: String, value: String	String	Set shared info field on a single file. Returns action ID.
set_personal_info	files: Array<DtFile>, field: String, type: String, value: String	()	Set personal info field value on files.
set_personal_info	file: DtFile, field: String, type: String, value: String	()	Set personal info field value on a single file.
star	files: Array<DtFile>	String	Star files. Returns action ID.
star	file: DtFile	String	Star a single file. Returns action ID.
unstar	files: Array<DtFile>	String	Unstar files. Returns action ID.
unstar	file: DtFile	String	Unstar a single file. Returns action ID.
set_folder_color	files: Array<DtFile>, color: String	String	Set folder color. Returns action ID.
set_folder_color	file: DtFile, color: String	String	Set folder color on a single folder. Returns action ID.
clear_folder_color	files: Array<DtFile>	String	Clear folder color. Returns action ID.
clear_folder_color	file: DtFile	String	Clear folder color on a single folder. Returns action ID.
set_description	file: DtFile, text: String	String	Set file description. Returns action ID.
report_save_to_drive	handle: INT	DtFile	Save report as Google Doc to Drive root. Uses the report title or a default.
report_save_to_drive	handle: INT, title: String	DtFile	Save report as Google Doc with custom title.
report_save_to_drive	handle: INT, options: Map	DtFile	Save report as Google Doc with options map.
transfer_ownership	files: Array<DtFile>, email: String	String	Queue ownership transfer. Returns action ID.
transfer_ownership	file: DtFile, email: String	String	Queue ownership transfer for a single file. Returns action ID.
accept_transfer	files: Array<DtFile>	String	Accept incoming transfers. Returns action ID.
accept_transfer	file: DtFile	String	Accept incoming transfer for a single file. Returns action ID.
accept_transfer	files: Array<DtFile>, options: Map	String	Accept incoming transfers with options. rename_originals: true renames originals in sender's Drive (default false).
accept_transfer	file: DtFile, options: Map	String	Accept incoming transfer for a single file with options.
reject_transfer	files: Array<DtFile>	String	Reject incoming transfers. Returns action ID.
reject_transfer	file: DtFile	String	Reject incoming transfer for a single file. Returns action ID.
cancel_transfer	files: Array<DtFile>	String	Cancel outgoing transfers. Returns action ID.
cancel_transfer	file: DtFile	String	Cancel outgoing transfer for a single file. Returns action ID.

All Types

DtFile

A Google Drive file or folder with read-only properties

Property	Type	Description
id	String	Google Drive file ID
name	String	File or folder name
mime_type	String	MIME type (empty for folders)
is_folder	bool	Whether this is a folder
size	INT	File size in bytes (0 for folders)
effective_size	INT	Effective size including Google Docs counted size
created	String	Creation timestamp (RFC 3339)
modified	String	Last modified timestamp (RFC 3339)
parent_id	String	Parent folder ID (empty if root)
owned_by_me	bool	Whether owned by the current user
shared_with_others	bool	Whether shared with others
labels	Array<String>	Personal labels assigned to this file
starred	bool	Whether starred (marked important)
description	String	File description text
can_delete	bool	Whether current user can delete
can_share	bool	Whether current user can share
can_download	bool	Whether current user can download
can_edit	bool	Whether current user can edit
can_rename	bool	Whether current user can rename
web_view_link	String	URL to view file in browser
file_extension	String	File extension (without dot)
folder_color	String	Folder color hex code
md5	String	MD5 checksum (files only)
version	INT	File version number

DtFilter

A validated filter expression for querying files Created with filter().

Property	Type	Description
expression	String	The raw filter expression
description	String	Human-readable description of the filter

DtSortOrder

A validated sort expression for ordering query results Created with sort_order().

Property	Type	Description
expression	String	The raw sort expression

DtPersonalLabel

A personal label for local file organization Created with personal_label().

Property	Type	Description
name	String	Label name

DtSharedLabel

A shared label visible to all users with access Created with shared_label().

Property	Type	Description
name	String	Shared label name

DtPersonalInfoField

A personal info field descriptor

Property	Type	Description
name	String	Field name
field_type	String	Field type

DtSharedInfoField

A shared info field descriptor

Property	Type	Description
group_name	String	Group name
field_name	String	Field name within the group

WsUser

A Google Workspace user from the Admin SDK directory

Property	Type	Description
email	String	Primary email address
full_name	String	Full display name
given_name	String	First name
family_name	String	Last name
suspended	bool	Whether account is suspended
archived	bool	Whether account is archived
is_admin	bool	Whether user is an admin
org_unit	String	Organizational unit path
has_2fa	bool	Whether 2FA is enabled
user_id	String	Google Workspace user ID