Skip to main content
Archil disks are currently in preview. The CLI is subject to change.
The following document provides a reference for all of the commands available in 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

​
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)
  • <MOUNTPOINT>: Local directory to mount the disk
Options: Connection & Authentication:
  • --region <REGION>: Region where the disk is located (e.g., aws-us-east-1, gcp-us-central1)
  • --auth-token <TOKEN>: Authentication token, if using
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]
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 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.

​
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
Note: Force checkout will revoke any existing delegation from another client and may result in data loss on the server currently holding the delegation.

​
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
⌘I