AO CLI

The AO CLI is a command-line program that uploads a folder on your computer to an AO project, or downloads a project's files into a folder. Use it instead of the browser for large amounts of data, many files, or a slow or unreliable connection: it can run unattended, retries files that fail, and a second run transfers only what's missing.

Get it and set it up

In AO, open Projects at the bottom of the left toolbar, turn off Private Projects so public projects are listed too, and open the AO Tools project. In its Files tab, download the newest AO CLI ZIP (aocli_binaries_ followed by a date) and unzip it. If you don't see AO Tools, contact support@terradepth.com.

The binaries folder inside has one program for each kind of computer, plus sample-settings.json and User-Readme.md:

1. In the binaries folder, copy sample-settings.json to a new file named settings.json and fill it in (see settings.json below). Replace every value in the sample, including URL.
2. Open a terminal in that folder: Command Prompt or PowerShell on Windows, Terminal on a Mac.
3. On a Mac or Linux, make the program runnable once, for example chmod +x aocli_darwin_arm64. If macOS then says it can't check the program, open System Settings > Privacy & Security and choose Open Anyway.
4. Run the program with version. This article covers Version: 1.7.2; if yours is older, download the newest ZIP from AO Tools.

In the examples below, type your program's name in place of aocli: aocli_windows_amd64.exe in Command Prompt, .\aocli_windows_amd64.exe in PowerShell, or ./aocli_darwin_arm64 on a Mac. Always run it from the folder that holds settings.json. Run it with no command to see every command and option. That list also shows file sync: don't use it; use file up and file down.

Sign in

The CLI signs in each time you upload or download. At Enter your password:, type your AO password; it isn't shown as you type, and it isn't saved. The CLI signs in to the URL in settings.json with its Email.

• If your account belongs to more than one organization, the CLI lists them and asks you to choose one. Type its name exactly as listed: capitals count. The project must be in that organization.
• The CLI signs in with an email and password only, not with single sign-on. If you sign in to AO with Microsoft or Google and have no AO password, set one with Forgot password? on the AO sign-in page. See Signing in and passwords.
• Long transfers renew your sign-in on their own, so they can run for many hours.
• To sign in with a different email for one run, put -u and the email before file. -p followed by your password skips the prompt, but it can show up in your command history: type the password at the prompt instead.

You need the same role as in the browser: Professionals and Admins can upload, and Users, Professionals and Admins can download.

Upload

Put your files in the folder named in Directory, with subfolders arranged the way you want them in the project, then run:

aocli file up

The CLI uploads every file in the folder and its subfolders into the project, except hidden and system files, such as .DS_Store, __MACOSX and Thumbs.db. Files at the top of the folder go to the top of the project, and its subfolders become folders in the project. ZIP files upload as ZIP files: to extract one in AO, choose Unzip on its row in the project's Files tab.

To see what's in the folder first, run aocli drive report. It counts the files and their total size by type, split into types AO can visualize and the rest, without signing in.

What happens when you upload:

1. After you sign in, the CLI compares your folder with the project (Checking for File Conflicts). Files already in AO with the same folder, name and content aren't uploaded again. A file with the same folder and name but different content is a conflict: see Conflicts below.
2. It shows a Pre Transfer Summary: the organization, project, folder and options, how many files are already uploaded, how conflicts will be handled, how many files it will transfer and how many of those AO can visualize, the total size, and a count and size for each file type. If the upload could take more than 8 hours, a WARNING gives an estimate, based on 2 MB/s for each file transferring at once.
3. At Do you want to continue with the transfer? (y/n):, type y to start or n to cancel.
4. While it runs, each file is listed as it finishes, and a progress line shows files done, failures, gigabytes transferred, speed and ETA (time remaining).
5. At the end, check the summary (see Check the summary below).

Options. Put -m (like -u and -p) before file, and the other options after file up or file down:

For example, to upload only GeoTIFFs, eight at a time, without the confirmation:

aocli -m "*.tif" file up --threads 8 --yes

Conflicts. OnConflict in settings.json decides what happens to a file that has the same folder and name on both sides but different content:

With KEEP_BOTH, every run adds another copy of a file that still differs, so use SKIP or OVERWRITE when you run the same upload again.

Check the summary. The upload ends with a summary titled Upload complete when every selected file is in AO, or Upload results when some aren't:

• Status: Success; Partial Success when some files failed or were skipped as conflicts; Failed when every file failed; Interrupted when the CLI stopped with files still waiting.
• Files: the files uploaded on the first pass and on retry, Confirmed already uploaded (in AO already, with the same content), Skipped (conflicts you chose to skip), Failed, and Pending (not started).
• Performance: how long it took, how much data moved, and the effective transfer rate.
• Final retry pass, when files failed the first time: how many were tried again, recovered and still failed.
• Summary: Files confirmed uploaded: with a count and percentage. All selected files are uploaded. No further action is needed. means you're done.

Above the summary, each file is listed as Uploaded file:, Confirmed already uploaded file:, Skipped conflicting file: or Failed file:. If AO timed out while a file uploaded but stored it anyway, the CLI checks that AO's copy matches yours (Upload confirmation pending; checking server.) and counts it under Confirmed stored after retry.

The CLI doesn't save the summary to a file: keep the window open and copy the summary if you need a record. When any file fails, the CLI ends with a nonzero exit code, so a script can check for it. A sign-in error, a settings.json error or a missing Directory folder still ends with code 0, so a script should also check the output for Status: Success.

Download

Run:

aocli file down

The CLI downloads the project's files into the folder named in Directory, creating it if needed, with the project's folders inside it. Each file arrives as itself, not in a ZIP. Files you already have with the same content are skipped. If you have them all, it says All files already exist and are identical on both sides. No transfer is needed.

Downloads work like uploads: the same sign-in, Pre Transfer Summary, confirmation, progress line and options, except --limit. A file on your computer with the same folder and name as one in AO but different content is a conflict, handled by OnConflict (see Conflicts above). The summary is titled Transfer Complete even when files failed, so check Status. It counts files Transferred, Skipped and Failed, with a Success Rate.

For example, to download only LAZ point clouds:

aocli -m "*.laz" file down

settings.json

settings.json tells the CLI where to connect and what to transfer. It belongs in the folder you run the CLI from. Each one names one project: for another project, use another folder with its own settings.json.

{
  "URL": "https://ao.terradepth.com",
  "Email": "you@example.com",
  "SurveyName": "Harbor Survey 2026",
  "Directory": "C:/Surveys/Harbor Survey 2026",
  "OnConflict": "SKIP"
}

Keep the setting names, quotes, colons and commas as in the example. Your password never goes in settings.json.

If a transfer stops or files fail

Run the same command again. Each run compares your folder with the project, so it transfers only what's missing, changed or failed:

• Uploads skip files already in AO with the same content, and the summary counts them as Confirmed already uploaded. To confirm them, the CLI downloads AO's copy of each one in full, one at a time, before the Pre Transfer Summary appears. On a slow or metered connection, a re-run of a mostly uploaded folder moves about as much data as is already in AO. If it can't confirm a file, the upload stops with Upload status uncertain for.
• Downloads skip files you already have with the same content.

Within a run, the CLI tries each failed file once more at the end. A file that fails both times is listed as Failed file:: run the command again, later if AO was busy.

If the CLI can't renew your sign-in during a long run, it stops starting files, lets the ones in progress finish, and counts the rest as Pending, with Status: Interrupted. Run the command again.

A file cut off part-way, for example when you close the window or press Ctrl+C, starts again from the beginning next time. After a cut-off download, the partial file on your computer counts as a conflict: choose Overwrite for it when the CLI asks, or delete it before you run the command again. If settings.json has "OnConflict": "SKIP", the CLI skips such a file without asking, and if nothing else is left to download, it still says All files already exist and are identical on both sides. Delete the partial file, or set OVERWRITE for that run.

If something goes wrong

Messages about one file start with Error transferring file and the file's path; the CLI carries on with the other files.

Related: Moving Files In and Out of AO · Best practices for loading data to AO · Managing files in a project