`archil` CLI

The archil CLI is the Linux system client you install with curl -s https://archil.com/install | sh to mount Archil disks on a Linux server. For a step-by-step walkthrough, see Mount on Linux (FUSE). To verify a versioned Linux artifact before installing it, see Verify Linux downloads. This page is a reference for every command and flag it accepts. To mount a disk on macOS, use the separate Archil for macOS app — it’s an FSKit-based menu bar app, not the archil CLI.

Global Options

archil [OPTIONS] <SUBCOMMAND>

Global Options:

--log-level <LEVEL>: Set log level (trace, debug, info, warn, error) [default: info]
--version: Print version information
--help: Show help message

Environment Variables

The following environment variables can be used to configure the Archil CLI:

Variable	Description
`ARCHIL_MOUNT_TOKEN`	The disk token used to authenticate a mount when not using AWS IAM. Generate one from the disk’s Details page in the Archil console. Pair with `sudo --preserve-env=ARCHIL_MOUNT_TOKEN` to pass it securely.

Example:

export ARCHIL_MOUNT_TOKEN="<your-disk-token>"
sudo --preserve-env=ARCHIL_MOUNT_TOKEN archil mount <disk-name> /mnt/data --region aws-us-east-1

Using --preserve-env=ARCHIL_MOUNT_TOKEN passes the disk token through sudo’s environment rather than the command line, preventing it from being visible in process listings (ps aux).

ARCHIL_MOUNT_TOKEN is not an API key. It grants access to a single disk for mounting; API keys authenticate requests to the Control Plane API and are separate.

mount

Mount a disk to a local directory.

archil mount <DISK_NAME> <MOUNTPOINT> --region <REGION> [OPTIONS]

Arguments:

<DISK_NAME>: An owner-qualified disk name (organization/disk-name|employee@email.com/disk-name) or disk ID (dsk-0123456789abcdef). Optionally append :/path to mount a subdirectory as the root (e.g., myorg/mydisk:/data).
<MOUNTPOINT>: Local directory to mount the disk

Options: Connection:

--region <REGION>: Region where the disk is located (e.g., aws-us-east-1, gcp-us-central1)

Cache Configuration:

--max-cache-mb <SIZE>: Maximum cache size in MB [default: 1/4 of available RAM or 2048 MiB, whichever is smaller]
--target-cache-mb <SIZE>: Target cache size in MB [default: 75% of the maximum cache size]
--pre-fetch <PATHS>: Comma-separated list of paths to pre-fetch into the cache after the mount completes (e.g., models,data/2024). Equivalent to running archil prefetch once the disk is mounted.

Behavior Options:

--shared: Enable sharing the disk with multiple clients by skipping the checkout of the root directory [default: false]. Without this flag, the client claims exclusive ownership of the root, and any attempt to mount the same disk from a second location will fail. See Shared Disks.
--enable-xattrs: Enable extended attributes [default: false]
--statistics: Enable statistics collection [default: false]
--force, -f: Force claim ownership of the root directory, immediately revoking the delegations of any other clients [default: false]
--branch <BRANCH>: Mount a specific branch of the disk instead of the root

Force claiming ownership of the root directory will immediately revoke the delegations of any other clients. This can result in data loss for any outstanding writes from other clients to the disk.

Process & Logging:

--no-fork: Launch without forking [default: false]
--log-dir <DIR>: Log to directory instead of journald
--max-log-size-mb <SIZE>: Maximum log file size in MB [default: 100]

Examples:

# Basic mount
archil mount <disk-name> /mnt/archil --region aws-us-east-1

# Mount a subdirectory as the root
archil mount <disk-name>:/data /mnt/data --region aws-us-east-1

# Mount with custom cache settings
archil mount <disk-name> /mnt/archil --region aws-us-east-1 --max-cache-mb 2048 --target-cache-mb 1024

# Mount in shared mode with statistics
archil mount <disk-name> /mnt/archil --region aws-us-east-1 --shared --statistics

# Mount and warm the cache with specific paths
archil mount <disk-name> /mnt/archil --region aws-us-east-1 --pre-fetch models,data/2024

# Mount with custom logging
archil mount <disk-name> /mnt/archil --region aws-us-east-1 --log-dir /var/log/archil --max-log-size-mb 50

Always use archil unmount to unmount your Archil disks, not the builtin umount command. Unlike umount, the archil unmount command does not exit until all pending data is flushed to the backing disk. This is particularly important on system shutdown, in which the Linux kernel will, by default, call umount on all devices and shutdown without waiting for pending Archil writes to be synced.

Subdirectory mounts

You can mount a subdirectory of a disk instead of the entire root by appending :/path to the disk name, following the same convention as NFS:

# Mount the /data directory as the local root
sudo archil mount myorg/mydisk:/data /mnt/data --region aws-us-east-1

# Mount a nested subdirectory
sudo archil mount myorg/mydisk:/projects/alpha /mnt/alpha --region aws-us-east-1

The client resolves the path at mount time by walking from the disk root to the target directory, following symlinks along the way. The resolved directory becomes the root of the FUSE mount — your application sees it as / and cannot traverse above it via ... The target path must be absolute (starting with / after the :) and must resolve to a directory that already exists on the disk. Delegations with subdirectory mounts When mounting exclusively (without --shared), the client checks out ownership of the subdirectory rather than the disk root. This means different clients can mount different subdirectories of the same disk simultaneously without delegation conflicts:

# Client A mounts /models exclusively
sudo archil mount myorg/mydisk:/models /mnt/models --region aws-us-east-1

# Client B mounts /data exclusively — no conflict with Client A
sudo archil mount myorg/mydisk:/data /mnt/data --region aws-us-east-1

The subdirectory must exist on the disk before mounting. Create it by first mounting the disk root, running mkdir, and then unmounting with archil unmount.

unmount

Unmount a disk.

archil unmount <MOUNTPOINT> [OPTIONS]

Arguments:

<MOUNTPOINT>: Directory where the disk is mounted

Options:

--force, -f: Force unmount operation, skipping fsyncing outstanding writes and releasing any ownership claims [default: false]

Force unmounting a disk will skip fsyncing outstanding writes. This will result in data loss for any outstanding writes.

Examples:

# Normal unmount
archil unmount /mnt/archil

# Force unmount
archil unmount /mnt/archil --force

version

Display version information.

archil version

checkout

Request an ownership claim on a file or directory.

archil checkout <PATH> [OPTIONS]

Arguments:

<PATH>: Path to the file to check out

Options:

--force, -f: Force checkout, revoking an existing delegation from another client [default: false]

Force checkout will revoke ownership that other clients have on parents of the affected file or children of the affected file. For more details, see the Shared Disks page.

Force checkout will revoke any existing delegation from another client. This can result in data loss for any outstanding writes from other clients to the affected file.

Examples:

# Normal checkout
archil checkout /mnt/archil/myfile.txt

# Force checkout (with confirmation prompt)
archil checkout /mnt/archil/myfile.txt --force

checkin

Check in a file, releasing ownership of a file or directory.

archil checkin <PATH>

Arguments:

<PATH>: Path to the file to check in

Examples:

# Check in a file
archil checkin /mnt/archil/myfile.txt

delegations

View the list of ownership claims that this client has on the disk mounted at <MOUNTPOINT>.

archil delegations <MOUNTPOINT>

Arguments:

<MOUNTPOINT>: Directory where the disk is mounted

Examples:

# View delegations
archil delegations /mnt/archil

status

Display status information for a mounted disk, for example, whether or not the disk has failed and is not accepting writes from this client.

archil status <MOUNTPOINT>

Arguments:

<MOUNTPOINT>: Directory where the disk is mounted

Examples:

# View disk status
archil status /mnt/archil

set-cache-expiry

Set the duration of time for which directories are kept cached locally instead of forcing a read from the server. This command configures the readdir cache expiry time for a specific directory.

archil set-cache-expiry <PATH> --readdir-expiry <SECONDS>

Arguments:

<PATH>: Path to the directory where cache expiry should be set

Options:

--readdir-expiry <SECONDS>: Cache expiry duration in seconds

Notes:

This command only applies to directories, not files
Setting expiry to 0 seconds disables caching for the specified directory
Cache settings help balance performance and data freshness
Longer expiry times improve performance but may show stale directory contents
The path must be on an Archil-mounted filesystem

Examples:

# Set directory cache expiry to 5 minutes (300 seconds)
archil set-cache-expiry /mnt/archil/my-directory --readdir-expiry 300

# Disable caching for a directory
archil set-cache-expiry /mnt/archil/real-time-data --readdir-expiry 0

# Set cache expiry to 1 hour (3600 seconds)
archil set-cache-expiry /mnt/archil/static-content --readdir-expiry 3600

invalidate-cache

Available in client v0.8.11 and later. Drop this client’s cached entries (and the kernel’s matching attribute, page, and dentry caches) so the next read goes back to the server. Pass the mount root to refresh everything, or a single file path to refresh just that file. Non-root directory paths are rejected. In-flight (dirty) writes are always preserved.

archil invalidate-cache <PATH>

Arguments:

<PATH>: An Archil mount root (whole-mount form) or a regular file inside an Archil mount (per-file form).

Examples:

# Whole mount
archil invalidate-cache /mnt/archil

# One file (siblings keep their cache)
archil invalidate-cache /mnt/archil/shared-data/report.csv

Stale data on a --shared mount typically means another client has updated files on the disk and your client is still serving cached entries. See Shared Disks for the full ownership and delegation model.

prefetch

Available in client v0.8.11 and later. Warm this client’s cache by reading paths into it ahead of time, so later reads are served locally instead of fetching from the server. Pass one or more files or directories; directories are fetched recursively. The command queues the work and returns immediately — fetching continues in the background.

archil prefetch <MOUNTPOINT> <PATH>...

Arguments:

<MOUNTPOINT>: Directory where the disk is mounted
<PATH>...: One or more paths to pre-fetch. Each path may be relative to the mount root (e.g., data/report.csv) or a full path under the mountpoint (e.g., /mnt/archil/data/report.csv) — the mountpoint prefix is stripped automatically, so shell tab-completion works.

Examples:

# Pre-fetch a single file
archil prefetch /mnt/archil data/report.csv

# Pre-fetch several paths at once (files and/or directories, fetched recursively)
archil prefetch /mnt/archil models config.yaml data/2024

# Full paths under the mountpoint also work
archil prefetch /mnt/archil /mnt/archil/models

Pre-fetched data is read into the same client cache as regular reads, so it counts against your cache size limits (--max-cache-mb). If you pre-fetch more than the cache can hold, earlier entries may be evicted before you read them. To warm the cache automatically as soon as a disk is mounted, use mount --pre-fetch.

checkpoints

Manage checkpoints: named, point-in-time snapshots of a disk’s filesystem state. A branch is always forked from a specific checkpoint. For details, see Branches & Checkpoints.

checkpoints create

Create a checkpoint capturing the current filesystem state of a mounted disk.

archil checkpoints create <MOUNTPOINT> <CHECKPOINT_NAME>

Arguments:

<MOUNTPOINT>: Local directory where the disk is mounted
<CHECKPOINT_NAME>: Name for the new checkpoint (must be unique within the current branch)

Examples:

# Checkpoint the current state of the disk mounted at /mnt/archil
archil checkpoints create /mnt/archil pre-migration

checkpoints list

List checkpoints on a branch (or on the root if --branch is omitted).

archil checkpoints list <DISK_ID> --region <REGION> [OPTIONS]

Arguments:

<DISK_ID>: Disk ID to list checkpoints for (e.g., dsk-0123456789abcdef)

Options:

--region <REGION>: Region where the disk is located (e.g., aws-us-east-1)
--branch <BRANCH>: Branch name to list checkpoints from. If omitted, lists checkpoints on the root.
--json: Output as JSON [default: false]

Examples:

# List checkpoints on the root
archil checkpoints list dsk-0123456789abcdef --region aws-us-east-1

# List checkpoints on a specific branch
archil checkpoints list dsk-0123456789abcdef --region aws-us-east-1 --branch experiment-1

# Machine-readable output
archil checkpoints list dsk-0123456789abcdef --region aws-us-east-1 --json

branches

Manage branches: independent, writable forks of a disk created from a checkpoint. Branches can be mounted with archil mount --branch. For details, see Branches & Checkpoints. branches subcommands require a --region flag:

archil branches --region <REGION> <SUBCOMMAND>

Options (apply to all branches subcommands):

--region <REGION>: Region where the disk is located (e.g., aws-us-east-1)

branches create

Create a new branch forking a specific checkpoint.

archil branches --region <REGION> create <DISK_ID> <BRANCH_NAME> --from-checkpoint <CHECKPOINT_NAME> [--from-branch <BRANCH>]

Arguments:

<DISK_ID>: Disk ID to branch from (e.g., dsk-0123456789abcdef)
<BRANCH_NAME>: Name for the new branch

Options:

--from-checkpoint <NAME>: Name of the checkpoint to branch from (required)
--from-branch <BRANCH>: Name of the branch the checkpoint is on. Defaults to the root.

Examples:

# Create a branch from a checkpoint on the root
archil branches --region aws-us-east-1 create dsk-0123456789abcdef experiment-1 \
    --from-checkpoint pre-migration

# Create a branch from a checkpoint that lives on another branch
archil branches --region aws-us-east-1 create dsk-0123456789abcdef experiment-2 \
    --from-checkpoint v1 --from-branch experiment-1

branches list

List branches on a disk as a tree. Each node shows the branch name and the checkpoint it was forked from.

archil branches --region <REGION> list <DISK_ID> [OPTIONS]

Arguments:

<DISK_ID>: Disk ID to list branches for (e.g., dsk-0123456789abcdef)

Options:

--limit <N>: Cap the number of branches shown in the tree. Excess branches are dropped newest-leaf-first, and a ... N more marker is rendered beneath the closest still-visible parent to indicate how many direct children were truncated. Ignored when --json is set.
--json: Output the full list as JSON, with no truncation [default: false]

Examples:

# Render the full branch tree
archil branches --region aws-us-east-1 list dsk-0123456789abcdef

# Cap the tree to the 10 oldest branches
archil branches --region aws-us-east-1 list dsk-0123456789abcdef --limit 10

# Machine-readable output (full list, never truncated)
archil branches --region aws-us-east-1 list dsk-0123456789abcdef --json

Getting started

Mounting

Compute

Concepts

Data Sources

Details

Administration

Protocols

SDKs

Integrations

Reference

Legal

Global Options

Environment Variables

mount

Subdirectory mounts

unmount

version

checkout

checkin

delegations

status

set-cache-expiry

invalidate-cache

prefetch

checkpoints

checkpoints create

checkpoints list

branches

branches create

branches list

​Global Options

​Environment Variables

​mount

​Subdirectory mounts

​unmount

​version

​checkout

​checkin

​delegations

​status

​set-cache-expiry

​invalidate-cache

​prefetch

​checkpoints

​checkpoints create

​checkpoints list

​branches

​branches create

​branches list

Global Options

Environment Variables

mount

Subdirectory mounts

unmount

version

checkout

checkin

delegations

status

set-cache-expiry

invalidate-cache

prefetch

checkpoints

checkpoints create

checkpoints list

branches

branches create

branches list