> ## 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. # `archil` CLI > Reference for the Linux system CLI that mounts Archil disks as local folders. 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)](/mounting/linux). This page is a reference for every command and flag it accepts. To mount a disk on macOS, use the separate [Archil for macOS](/mounting/macos) app — it's an FSKit-based menu bar app, not the `archil` CLI. ## Global Options ```bash theme={null} archil [OPTIONS] ``` **Global Options:** * `--log-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](/concepts/disk-users#disk-token-authorization) 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:** ```bash theme={null} export ARCHIL_MOUNT_TOKEN="" sudo --preserve-env=ARCHIL_MOUNT_TOKEN archil mount /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](/api-reference/introduction) and are separate. ## mount Mount a disk to a local directory. ```bash theme={null} archil mount --region [OPTIONS] ``` **Arguments:** * ``: 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](#subdirectory-mounts) as the root (e.g., `myorg/mydisk:/data`). * ``: Local directory to mount the disk **Options:** **Connection:** * `--region `: Region where the disk is located (e.g., `aws-us-east-1`, `gcp-us-central1`) **Cache Configuration:** * `--max-cache-mb `: Maximum cache size in MB \[default: 1/4 of available RAM or 2048 MiB, whichever is smaller] * `--target-cache-mb `: Target cache size in MB \[default: 75% of the maximum cache size] * `--pre-fetch `: 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`](#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](/concepts/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 `: Mount a specific [branch](#branches) 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 `: Log to directory instead of journald * `--max-log-size-mb `: Maximum log file size in MB \[default: 100] **Examples:** ```bash theme={null} # Basic mount archil mount /mnt/archil --region aws-us-east-1 # Mount a subdirectory as the root archil mount :/data /mnt/data --region aws-us-east-1 # Mount with custom cache settings archil mount /mnt/archil --region aws-us-east-1 --max-cache-mb 2048 --target-cache-mb 1024 # Mount in shared mode with statistics archil mount /mnt/archil --region aws-us-east-1 --shared --statistics # Mount and warm the cache with specific paths archil mount /mnt/archil --region aws-us-east-1 --pre-fetch models,data/2024 # Mount with custom logging archil mount /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: ```bash theme={null} # 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](/concepts/shared-disks) conflicts: ```bash theme={null} # 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. ```bash theme={null} archil unmount [OPTIONS] ``` **Arguments:** * ``: 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:** ```bash theme={null} # Normal unmount archil unmount /mnt/archil # Force unmount archil unmount /mnt/archil --force ``` ## version Display version information. ```bash theme={null} archil version ``` ## checkout Request an ownership claim on a file or directory. ```bash theme={null} archil checkout [OPTIONS] ``` **Arguments:** * ``: 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](/concepts/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:** ```bash theme={null} # 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. ```bash theme={null} archil checkin ``` **Arguments:** * ``: Path to the file to check in **Examples:** ```bash theme={null} # 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 ``. ```bash theme={null} archil delegations ``` **Arguments:** * ``: Directory where the disk is mounted **Examples:** ```bash theme={null} # 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. ```bash theme={null} archil status ``` **Arguments:** * ``: Directory where the disk is mounted **Examples:** ```bash theme={null} # 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. ```bash theme={null} archil set-cache-expiry --readdir-expiry ``` **Arguments:** * ``: Path to the directory where cache expiry should be set **Options:** * `--readdir-expiry `: 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:** ```bash theme={null} # 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. ```bash theme={null} archil invalidate-cache ``` **Arguments:** * ``: An Archil mount root (whole-mount form) or a regular file inside an Archil mount (per-file form). **Examples:** ```bash theme={null} # 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](/concepts/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. ```bash theme={null} archil prefetch ... ``` **Arguments:** * ``: Directory where the disk is mounted * `...`: 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:** ```bash theme={null} # 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`](#mount). ## checkpoints Manage checkpoints: named, point-in-time snapshots of a disk's filesystem state. A [branch](#branches) is always forked from a specific checkpoint. For details, see [Branches & Checkpoints](/concepts/branches-and-checkpoints). ### checkpoints create Create a checkpoint capturing the current filesystem state of a mounted disk. ```bash theme={null} archil checkpoints create ``` **Arguments:** * ``: Local directory where the disk is mounted * ``: Name for the new checkpoint (must be unique within the current branch) **Examples:** ```bash theme={null} # 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). ```bash theme={null} archil checkpoints list --region [OPTIONS] ``` **Arguments:** * ``: Disk ID to list checkpoints for (e.g., `dsk-0123456789abcdef`) **Options:** * `--region `: Region where the disk is located (e.g., `aws-us-east-1`) * `--branch `: Branch name to list checkpoints from. If omitted, lists checkpoints on the root. * `--json`: Output as JSON \[default: false] **Examples:** ```bash theme={null} # 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](#checkpoints). Branches can be mounted with [`archil mount --branch`](#mount). For details, see [Branches & Checkpoints](/concepts/branches-and-checkpoints). `branches` subcommands require a `--region` flag: ```bash theme={null} archil branches --region ``` **Options (apply to all `branches` subcommands):** * `--region `: Region where the disk is located (e.g., `aws-us-east-1`) ### branches create Create a new branch forking a specific checkpoint. ```bash theme={null} archil branches --region create --from-checkpoint [--from-branch ] ``` **Arguments:** * ``: Disk ID to branch from (e.g., `dsk-0123456789abcdef`) * ``: Name for the new branch **Options:** * `--from-checkpoint `: Name of the checkpoint to branch from (required) * `--from-branch `: Name of the branch the checkpoint is on. Defaults to the root. **Examples:** ```bash theme={null} # 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. ```bash theme={null} archil branches --region list [OPTIONS] ``` **Arguments:** * ``: Disk ID to list branches for (e.g., `dsk-0123456789abcdef`) **Options:** * `--limit `: 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:** ```bash theme={null} # 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 ```