Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.archil.com/llms.txt

Use this file to discover all available pages before exploring further.

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). 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:
VariableDescription
ARCHIL_MOUNT_TOKENThe 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]
Behavior Options:
  • --shared: Enable sharing the disk with multiple clients by skipping the checkout of the root directory [default: false]
  • --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 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.

​
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