id = "juicefs"
name = "JuiceFS"
homepage = "https://juicefs.com/"
description = "JuiceFS is a distributed POSIX file system built on top of Redis and S3."
executables = ["juicefs"]

[dotfiles]

# JuiceFS's command reference says --conf-dir defaults to ~/.juicefs, and its
# automation guide shows the generated per-volume files as ~/.juicefs/*.conf.
paths = ["~/.juicefs/"]
# The same directory also contains the client cache, which is machine-local
# state rather than portable configuration.
exclude = [
  "~/.juicefs/cache/",
]
# The official automation example shows password, accesskey, secretkey, and
# token in every generated file; the volume name is arbitrary, so protect the
# whole glob rather than pretending a single volume name is exhaustive.
secret = ["~/.juicefs/*.conf"]

[commands]
format = 1
label = "JuiceFS"
description = "Create, mount and unmount JuiceFS volumes. Metadata, cache, FUSE tuning, gateway, sync and the other tools are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.subcommand]]
path = ["format"]
label = "Create a volume"
description = "Format a file system on a metadata engine. Credentials passed as flags show up in shell history; the ACCESS_KEY and SECRET_KEY environment variables are safer and not covered here."

[[commands.subcommand.source]]
id = "ref"
kind = "manual"
url = "https://juicefs.com/docs/community/command_reference#format"
revision = "main 2026-10-27"
evidence = """
juicefs format [command options] META-URL NAME
|`META-URL`|Database URL of the metadata engine.|
|`NAME`|Name of the file system|
|`--force`|overwrite existing format (default: false)|
|`--storage=file`|Object storage type (e.g. `s3`, `gs`, `oss`, `cos`) (default: `file`)|
|`--bucket=/var/jfs`|A bucket URL to store data|
|`--compress=none`|compression algorithm, choose from `lz4`, `zstd`, `none` (default).|
|`--capacity=0`|storage space limit in GiB, default to 0 which means no limit.|
|`--inodes=0`|Limit the number of inodes, default to 0 which means no limit.|
|`--trash-days=1`|number of days before trash files are expired, set to 0 to disable trash.|
"""

[[commands.subcommand.field]]
id = "meta_url"
label = "Metadata URL"
description = "For example redis://localhost or sqlite3://myjfs.db."
type = "string"
position = 0
sources = ["ref"]

[[commands.subcommand.field]]
id = "name"
label = "Volume name"
type = "string"
position = 1
sources = ["ref"]

[[commands.subcommand.field]]
id = "storage"
label = "Object storage type"
type = "string"
option = ["--storage"]
suggestions = [{ value = "file", label = "Local files" }, { value = "s3", label = "S3" }, { value = "gs", label = "Google Cloud Storage" }, { value = "oss", label = "Aliyun OSS" }, { value = "cos", label = "Tencent COS" }]
sources = ["ref"]

[[commands.subcommand.field]]
id = "bucket"
label = "Bucket URL or directory"
type = "string"
option = ["--bucket"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "compress"
label = "Compression"
type = "enum"
option = ["--compress"]
choices = [{ value = "none", label = "None" }, { value = "lz4", label = "lz4" }, { value = "zstd", label = "zstd" }]
sources = ["ref"]

[[commands.subcommand.field]]
id = "capacity"
label = "Capacity limit (GiB)"
type = "integer"
option = ["--capacity"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "inodes"
label = "Inode limit"
type = "integer"
option = ["--inodes"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "trash_days"
label = "Trash retention (days)"
description = "0 disables the trash."
type = "integer"
option = ["--trash-days"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "force"
label = "Overwrite existing format"
type = "boolean"
option = ["--force"]
effect = "overwrite"
sources = ["ref"]

[[commands.subcommand.task]]
id = "local-test"
label = "Local test volume"
fields = ["meta_url", "name", "storage", "bucket"]
required = ["meta_url", "name"]

[[commands.subcommand.task]]
id = "object-storage"
label = "Object-storage volume"
fields = ["meta_url", "name", "storage", "bucket", "compress", "capacity", "trash_days"]
required = ["meta_url", "name", "storage", "bucket"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["meta_url", "name", "storage", "bucket"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["compress", "capacity", "inodes", "trash_days", "force"]

[[commands.subcommand]]
path = ["mount"]
label = "Mount a volume"
description = "Mount a formatted volume. Cache, metadata and FUSE tuning options are left out."

[[commands.subcommand.source]]
id = "ref"
kind = "manual"
url = "https://juicefs.com/docs/community/command_reference#mount"
revision = "main 2026-10-27"
evidence = """
juicefs mount [command options] META-URL MOUNTPOINT
|`META-URL`|Database URL of the metadata engine.|
|`MOUNTPOINT`|file system mount point, e.g. `/mnt/jfs`, `Z:`.|
|`-d, --background`|run in background (default: false)|
|`--log=path`|path of log file when running in background|
|`--force`|force to mount even if the mount point is already mounted by the same filesystem.|
juicefs mount redis://localhost /mnt/jfs --subdir /dir/in/jfs
juicefs mount redis://localhost /mnt/jfs -d --writeback
juicefs mount redis://localhost /mnt/jfs -d --read-only
"""

[[commands.subcommand.field]]
id = "meta_url"
label = "Metadata URL"
type = "string"
position = 0
sources = ["ref"]

[[commands.subcommand.field]]
id = "mountpoint"
label = "Mount point"
type = "path"
position = 1
path = { kind = "directory", role = "output" }
sources = ["ref"]

[[commands.subcommand.field]]
id = "background"
label = "Run in background"
type = "boolean"
option = ["--background", "-d"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "read_only"
label = "Read-only"
type = "boolean"
option = ["--read-only"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "writeback"
label = "Writeback cache"
description = "Faster writes at the risk of losing objects."
type = "boolean"
option = ["--writeback"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "subdir"
label = "Sub-directory as root"
type = "string"
option = ["--subdir"]
sources = ["ref"]

[[commands.subcommand.field]]
id = "log"
label = "Log file (background)"
type = "path"
option = ["--log"]
path = { kind = "file", role = "output" }
sources = ["ref"]

[[commands.subcommand.field]]
id = "force"
label = "Force mount"
type = "boolean"
option = ["--force"]
effect = "overwrite"
sources = ["ref"]

[[commands.subcommand.task]]
id = "mount-bg"
label = "Mount in background"
set = { background = [true] }
fields = ["meta_url", "mountpoint", "background", "read_only", "subdir"]
required = ["meta_url", "mountpoint"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["meta_url", "mountpoint", "background", "read_only"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["writeback", "subdir", "log", "force"]

[[commands.subcommand]]
path = ["umount"]
label = "Unmount a volume"
description = "Unmount a JuiceFS mount point."

[[commands.subcommand.source]]
id = "ref"
kind = "manual"
url = "https://juicefs.com/docs/community/command_reference#umount"
revision = "main 2026-10-27"
evidence = """
juicefs umount [command options] MOUNTPOINT
|`-f, --force`|force unmount a busy mount point (default: false)|
|`--flush`|wait for all staging chunks to be flushed (default: false)|
"""

[[commands.subcommand.field]]
id = "mountpoint"
label = "Mount point"
type = "path"
position = 0
path = { kind = "directory", role = "input" }
sources = ["ref"]

[[commands.subcommand.field]]
id = "force"
label = "Force unmount a busy mount"
type = "boolean"
option = ["--force", "-f"]
effect = "overwrite"
sources = ["ref"]

[[commands.subcommand.field]]
id = "flush"
label = "Flush staged chunks first"
type = "boolean"
option = ["--flush"]
sources = ["ref"]

[[commands.subcommand.task]]
id = "umount"
label = "Unmount"
fields = ["mountpoint", "flush"]
required = ["mountpoint"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["mountpoint", "flush", "force"]