archmage drive

The drive subcommand pulls spreadsheets from Google Drive down to a local directory, so that the regular pipelines — archmage export and archmage struct — can consume them.

It has four subcommands: login authorizes Archmage to read your Google Drive, logout signs it back out, list shows the spreadsheets under a Drive folder, and download pulls them into a local directory.

Everything here is read-only. Archmage never uploads, and never writes back to Drive.

Before You Start

Before getting your spreadsheets from Google Drive, go through Setting Up Google Drive Access, so you can actually grab them.

Usage

archmage drive login --credentials <file> [flags]
archmage drive logout
archmage drive list --root <url> [flags] [<path1> <path2> ...]
archmage drive download --root <url> -o <output-dir> [flags] [<path1> <path2> ...]

# Authorize with your Google Drive credentials file
archmage drive login --credentials ./google-drive-credentials.json

# See what is under a folder
archmage drive list --root https://drive.google.com/drive/folders/1AbCdEf

# Pull everything into ./configs
archmage drive download --root https://drive.google.com/drive/folders/1AbCdEf \
    -o ./configs

# Download all “battle*” files
archmage drive download --root https://drive.google.com/drive/folders/1AbCdEf \
    -o ./configs "battle*"

What Gets Pulled

Under the --root folder, Archmage recognizes four things:

What’s in Drive	What happens
Folder	Archmage goes in and pulls its contents
Google Sheet	Exported as .xlsx
Uploaded .xlsx, .xlsm, .csv	Downloaded as-is
Shortcut	Resolved to whatever it points to

A Google Sheet has no extension on Drive, so when it’s pulled, .xlsx is added to its name — a sheet named hero lands as hero.xlsx.

Everything else in the folder — documents, slides, PDFs, images — is skipped.

archmage drive login

login runs the authorization once and saves the result to your machine. list and download just work after that.

On a machine with a browser, login shows a link and attempts to open it automatically, then waits for you to complete the sign-in.

Without a browser, there are two steps:

1. Run archmage drive login --export on a machine that has a browser.
2. Paste the login result into archmage drive login --import on the machine you’re setting up.

--credentials

Path to the Google Drive credentials JSON file. Required unless --import is used.

See Setting Up Google Drive Access how to get the file.

--export

Print the login result instead of saving it locally.

Caution

The login result grants read-only access to your Google Drive. Transfer it privately.

archmage drive login --export --credentials ./credentials.json > login.json

--import

Import the login result generated by --export from stdin.

archmage drive login --import < login.json

--url

Show the login URL without opening it in your browser automatically.

archmage drive logout

logout signs this machine out of Google Drive.

archmage drive list

list goes through the Google Drive folder you set with the --root CLI flag and shows what it finds, one item per line: modification time, a validity mark, and the path as it appears in Drive, relative to --root. A trailing / means it’s a folder.

list and download handle path patterns the same way, so you can test a wildcard with list first, then use it with download unchanged.

archmage drive list --root https://drive.google.com/drive/folders/1AbCdEf

2026-08-20 14:02:31 [ ] main/
2026-08-21 09:31:07 [!] main/hero
2026-08-21 09:31:07 [!] main/hero.xlsx
2026-08-25 11:00:44 [v] main/raw.csv
2026-08-25 11:00:58 [ ] main/skill/
2026-08-27 18:44:12 [v] main/skill/buff
2026-08-19 08:12:05 [x] main/中文表格

Mark	Meaning
[v]	A file download will get
[x]	A name Archmage does not accept; download will not handle this entry
[!]	Clashes with another entry in the same folder
[ ]	A valid folder

--concurrency

Number of concurrent Google Drive requests (default: 3).

Valid values: 1 to 16.

--cwd

Change the working directory before running. Relative paths are resolved from this directory.

--dotenv

Load environment variables from the specified file before running. If omitted and a .env file exists in the working directory, it’s loaded automatically.

--rate-limit

Maximum number of Google Drive requests per second (default: 10).

Valid values: 1 to 100.

--root

URL or ID of the Google Drive folder to use as the starting point. Required.

Form	Example
Folder URL	https://drive.google.com/drive/folders/1AbCdEf
Folder URL with an account segment	https://drive.google.com/drive/u/0/folders/1AbCdEf
open?id= URL	https://drive.google.com/open?id=1AbCdEf
Bare folder ID	1AbCdEf

Any query string in the URL is ignored.

--verbose / -v

Print extra status messages.

archmage drive download

download pulls the specified spreadsheets into --output-dir, preserving each file’s relative path.

--banner

Print the Archmage banner on startup.

--concurrency

Number of concurrent Google Drive requests (default: 3).

Valid values: 1 to 16.

--cwd

Change the working directory before running. Relative paths are resolved from this directory.

--dotenv

Load environment variables from the specified file before running. If omitted and a .env file exists in the working directory, it’s loaded automatically.

--force

Download every specified file, even if unchanged.

--output-dir / -o

The directory where downloaded files are written. Required.

--prune

Delete local files that no longer exist in Drive. Without --prune, such files are kept on disk.

archmage drive download --root https://drive.google.com/drive/folders/1AbCdEf \
    -o ./configs --prune

Note

--prune requires a full download — drop all path patterns.

Note

--prune only deletes files that were previously downloaded by this tool.

--rate-limit

Maximum number of Google Drive requests per second (default: 10).

Valid values: 1 to 100.

--root

URL or ID of the Google Drive folder to use as the starting point. Required.

See --root under list.

--verbose / -v

Print extra status messages.

Path Patterns

list and download accept path patterns that select part of the file tree.

• A pattern is relative to --root, with / between path segments.
• With no patterns, the whole tree under --root is selected.
• If a pattern points to a folder, it selects that folder and everything beneath it.
• Wildcards — *, ?, [...] — are allowed. Matching is case-sensitive on every platform.

# One folder and everything under it
archmage drive download --root <url> -o ./configs combat

# Files starting with 'item-' or 'skill-' inside main/
archmage drive download --root <url> -o ./configs "main/item-*" "main/skill-*"

The Download Manifest

download keeps a manifest file named drive.manifest in --output-dir, meant to be committed to the repository together with the downloaded files.

The manifest records each file’s Drive modification time, so later runs skip files that Drive reports as unchanged and download only the rest. --force overrides this.

If a file disappears from Drive, it stays on local disk and in the manifest by default. Pass --prune to remove it.