> ## Documentation Index > Fetch the complete documentation index at: https://docs.idyl.network/llms.txt > Use this file to discover all available pages before exploring further. # idyl filesystem > Manage filesystems in a namespace Manage the Filesystems of a Namespace. A Filesystem is a durable, versioned tree of files that Pods in its subnet mount by name. Like a Computer, it keeps its files as numbered saved versions in a history, so the same commands copy files in and out, save, restore, go back, and manage branches and Trash. A Filesystem lives in the subnet it is created in, so every command addresses the subnet selected by --subnet, IDYL\_SUBNET, or the current context. Names are unique within a Namespace and subnet together. ## Usage ```bash theme={null} idyl filesystem ``` ## Aliases * `filesystems` * `fs` ## Commands | Command | Description | | - | - | | `idyl filesystem branches` | List, name or discard branches of a filesystem's history | | `idyl filesystem commit` | Save a filesystem's current files | | `idyl filesystem cp` | Copy files between this machine and saved filesystem versions | | `idyl filesystem create` | Create a filesystem | | `idyl filesystem delete` | Delete a filesystem | | `idyl filesystem edit` | Edit a filesystem's size | | `idyl filesystem files` | List, delete or rename saved filesystem files | | `idyl filesystem fork` | Create a filesystem from a saved version and its history | | `idyl filesystem get` | Get filesystem details or list filesystems | | `idyl filesystem go-back` | Go back to an earlier point in a filesystem's history | | `idyl filesystem restore` | Restore saved files as a new filesystem version | | `idyl filesystem trash` | List, restore or delete forever branches in a filesystem's Trash | | `idyl filesystem versions` | List or name saved filesystem versions | ## Inherited flags | Flag | Description | | - | - | | `-a , --account-id ` | Account ID to use, overriding the current context. | | `-c , --context ` | Use the named context for this command. | | `--homedir ` | Override the configuration directory. Defaults to \~/.config/idyl. | | `-n , --namespace ` | Namespace to address, overriding the entered context. | | `--network ` | Override the Network for this command. | | `-p , --profile ` | Override the access profile for this command. | | `-s , --subnet ` | Subnet to use for this command, overriding the current context. | ## Subcommand reference ### `idyl filesystem branches` List the branches of a Filesystem's history. A branch is the entries that leave another path at one point, identified as \{segment}.\{afterSeq}, with its entry and version counts and its tips. The branch holding the current point is marked current. A Filesystem operand is its name, or its ID in the canonical form (lowercase 8-4-4-4-12 hexadecimal), which addresses the Filesystem by ID. \--name \=\ names a branch, and --unname \ removes its name; names are unique within the Filesystem. --trash \ moves a branch to Trash and waits until it is there: its versions stay complete and restorable with 'idyl filesystem trash --restore' until they are deleted forever. The branch holding the current point cannot be moved to Trash. Naming and Trash print the branch or Trash entry instead of a list. \--limit requests a page size, and --continue resumes a listing with the value the previous page returned. JSON and YAML preserve the server's envelope. #### Usage ```bash theme={null} idyl filesystem branches [flags] ``` #### Flags | Flag | Description | | - | - | | `--continue ` | Opaque continuation value returned by the previous page. | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `--limit ` | Maximum branches in one page; the server chooses the default when omitted. Default: `0`. | | `--name ` | Name a branch, as \=\. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--trash ` | Move a branch to Trash. | | `--unname ` | Remove a branch's name. | #### Examples ```bash theme={null} idyl filesystem branches datasets idyl filesystem branches datasets --name 3.12=experiment idyl filesystem branches datasets --trash 3.12 ``` ### `idyl filesystem commit` Save the Filesystem's current files and wait for its recorded outcome. The result is saved as a new version, unchanged at the existing version, or failed with the server's reason. This command does not run a process. A Filesystem operand is its name, or its ID in the canonical form (lowercase 8-4-4-4-12 hexadecimal), which addresses the Filesystem by ID. \--idempotency-key identifies this request. Reuse the same key and request to recover an uncertain outcome without starting another save. When omitted, the CLI chooses a key and reports it if the wait is interrupted. Ctrl-C stops waiting; the recorded operation may still complete. #### Usage ```bash theme={null} idyl filesystem commit [flags] ``` #### Flags | Flag | Description | | - | - | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | #### Examples ```bash theme={null} idyl filesystem commit datasets idyl filesystem commit datasets --idempotency-key before-cleanup -o json ``` ### `idyl filesystem cp` Copy files or directories between this machine and a Filesystem. Exactly one operand is name\[@version]:path, where name may also be the Filesystem's ID. Filesystem paths are relative POSIX paths; name: addresses the root. Prefix a local path containing a colon with ./. Downloads read one saved version throughout the copy. --save-first saves the current files first and reads precisely that version. Uploads publish one new version, reported as "saved as vN"; @version selects the upload's base, preserving later machine saves on other paths. A directory upload puts its contents under the destination path; an empty path puts them at the Filesystem root. A local operand of - streams a POSIX tar archive instead of a local path: a download writes the saved tree below the path to standard output, and an upload reads an archive from standard input and puts its entries under the destination path. Status is written to standard error. Symbolic links are copied as links, never followed. File modes are retained; ownership and timestamps are not. The local filesystem must support each saved name. Downloads replace each file only after its complete size and hash have been checked. A failed directory copy may leave files already copied, but never a partially replaced file. \--idempotency-key identifies an upload or a save-first request. Reuse the same key and unchanged request after an uncertain response. Ctrl-C stops the transfer or wait; an admitted publication may still complete. #### Usage ```bash theme={null} idyl filesystem cp [flags] ``` #### Flags | Flag | Description | | - | - | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--save-first` | Save current files before a download; cannot be combined with @version. | #### Examples ```bash theme={null} idyl filesystem cp ./report.txt datasets:report.txt idyl filesystem cp ./assets datasets:assets idyl filesystem cp datasets@v2:report.txt ./report.txt idyl filesystem cp 01954e20-7540-7ec4-93ec-14f783e6ab35@v2:assets ./assets idyl filesystem cp datasets:assets ./backup --save-first idyl filesystem cp datasets@v2:assets - > assets.tar tar -cf - -C ./site . | idyl filesystem cp - datasets:site ``` ### `idyl filesystem create` Create a Filesystem in the resolved Namespace and subnet. \--size requests its size and --headroom the reservation for outstanding changes; omitted, they come from the subnet's and then the Account's defaults. --store selects an admitted Store ('idyl store get' lists them); omitted, the subnet's default Store is used. The Store is fixed at creation. \--fork-of \@\ creates the Filesystem as a copy of a saved version and its history, and waits until the copy is done, as 'idyl filesystem fork' does. --idempotency-key identifies a fork; reuse it with the same request after an uncertain response. A create without --fork-of takes no key, as a Computer create does: retrying it is refused once the name exists. #### Usage ```bash theme={null} idyl filesystem create [flags] ``` #### Flags | Flag | Description | | - | - | | `--fork-of ` | Create as a copy of a saved version, as datasets\@v12. | | `--headroom ` | Requested reservation for outstanding changes, such as 2Gi. | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--size ` | Requested size, such as 10Gi. | | `--store ` | Admitted Store name; fixed after creation. | #### Examples ```bash theme={null} idyl filesystem create datasets idyl filesystem create datasets --size 50Gi --store archive idyl filesystem create datasets-copy --fork-of datasets@v12 ``` ### `idyl filesystem delete` Delete a Filesystem. The platform records the deletion and refuses new writers; the Filesystem reads as terminating until its removal completes. Asks for confirmation unless --yes is given. #### Usage ```bash theme={null} idyl filesystem delete [flags] ``` #### Aliases * `rm` #### Flags | Flag | Description | | - | - | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `-y, --yes` | Skip confirmation prompts. | #### Examples ```bash theme={null} idyl filesystem delete datasets idyl filesystem delete datasets --yes -o json ``` ### `idyl filesystem edit` Edit a Filesystem's requested size and headroom. Settings no flag names keep their values. The server reports a pending reservation when a running writer cannot apply the change yet, so an accepted request does not mean the new reservation is in force. The Store is fixed at creation. #### Usage ```bash theme={null} idyl filesystem edit [flags] ``` #### Flags | Flag | Description | | - | - | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--set-headroom ` | Requested reservation for outstanding changes, such as 8Gi. | | `--set-size ` | Requested size, such as 100Gi. | #### Examples ```bash theme={null} idyl filesystem edit datasets --set-size 100Gi idyl filesystem edit datasets --set-headroom 8Gi ``` ### `idyl filesystem files` List the entries of one saved Filesystem directory, or delete and rename saved paths. The operand is name\[@version]\[:path]; without a path it is the root, and without @version the latest saved version, or with --save-first the version a save of the current files returns. A Filesystem operand is its name, or its ID in the canonical form (lowercase 8-4-4-4-12 hexadecimal), which addresses the Filesystem by ID. A listing shows each entry's type, permission bits, size, and name, and a symbolic link's target; a file's SHA-256 is in JSON and YAML. Every name is shown with its non-printable characters escaped. A listing reads exactly one saved version, which is written to standard error; --limit requests a page size, and --continue resumes with the value the previous page returned. JSON and YAML preserve the server's listing envelope. \--delete \ and --rename \=\ change saved files: every change the command names is published together as one new version, reported as "saved as vN", on @version when given and otherwise on the current files. Deleting a directory deletes what it contains. A rename's source is split from its destination at the first =; destination names must be UTF-8 in NFC form. Earlier versions keep the old files, so 'idyl filesystem restore' brings them back. \--idempotency-key identifies a change or a save-first request. Reuse the same key and unchanged request after an uncertain response. #### Usage ```bash theme={null} idyl filesystem files [@version][:path] [flags] ``` #### Flags | Flag | Description | | - | - | | `--continue ` | Opaque continuation value returned by the previous page. | | `--delete ` | Delete a saved path in the new version; repeat for more. | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `--limit ` | Maximum entries in one page; the server chooses the default when omitted. Default: `0`. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--rename ` | Rename a saved path in the new version, as from=to; repeat for more. | | `--save-first` | Save current files before listing; cannot be combined with @version. | #### Examples ```bash theme={null} idyl filesystem files datasets idyl filesystem files datasets@v2:assets -o json idyl filesystem files datasets:logs --save-first idyl filesystem files datasets --delete tmp --delete build/cache idyl filesystem files datasets --rename notes.txt=docs/notes.txt ``` ### `idyl filesystem fork` Copy a saved Filesystem version and its history into a new Filesystem in the same Namespace and subnet. Use v2 or a saved-version name after @. The source version's immutable owning journal entry fixes the copy; later changes or deletion of the source do not change the new Filesystem. Running sessions and execution authority are not copied. A Filesystem operand is its name, or its ID in the canonical form (lowercase 8-4-4-4-12 hexadecimal), which addresses the Filesystem by ID. The command waits for the new Filesystem's recorded fork outcome. Ctrl-C stops waiting without cancelling the copy. Reuse --idempotency-key with the same request to find its recorded outcome after an uncertain response. When omitted, the CLI chooses a key and reports it if recovery is needed. #### Usage ```bash theme={null} idyl filesystem fork @ [flags] ``` #### Flags | Flag | Description | | - | - | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | #### Examples ```bash theme={null} idyl filesystem fork datasets@v2 datasets-copy idyl filesystem fork datasets@before-cleanup experiment --idempotency-key experiment-fork -o json ``` ### `idyl filesystem get` Get details of a Filesystem, or list the Filesystems of the resolved Namespace and subnet. A Filesystem operand is its name, or its ID in the canonical form (lowercase 8-4-4-4-12 hexadecimal), which addresses the Filesystem by ID. With no name, lists them; -A lists across every Namespace in the Account. \--limit requests a page size, and --continue resumes a listing with the value the previous page returned. JSON and YAML preserve the server's envelope. #### Usage ```bash theme={null} idyl filesystem get [name] [flags] ``` #### Aliases * `list` * `ls` #### Flags | Flag | Description | | - | - | | `-A, --all-namespaces` | List across every namespace in the account. | | `--continue ` | Opaque continuation value returned by the previous page. | | `--limit ` | Maximum filesystems in one page; the server chooses the default when omitted. Default: `0`. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | #### Examples ```bash theme={null} idyl filesystem get idyl filesystem get -A idyl filesystem get datasets -o json ``` ### `idyl filesystem go-back` Move the Filesystem's current point back to a saved version (v41 or its name) or a journal entry ID, or with --undo to where the last go-back left. The files become the version at that point, and the next change starts a new branch from it. Nothing is deleted: the entries left behind stay as a branch, which this command names, and 'idyl filesystem branches' lists. Unsaved work of a running writer is discarded, and its next start begins at the new point. A Filesystem operand is its name, or its ID in the canonical form (lowercase 8-4-4-4-12 hexadecimal), which addresses the Filesystem by ID. The command waits for the move's recorded outcome. --idempotency-key identifies the request; reuse it with the same request after an uncertain response. JSON and YAML print the move. #### Usage ```bash theme={null} idyl filesystem go-back [version|version-name|entry-id] [flags] ``` #### Flags | Flag | Description | | - | - | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--undo` | Return to where the last go-back left. | #### Examples ```bash theme={null} idyl filesystem go-back datasets v41 idyl filesystem go-back datasets before-cleanup idyl filesystem go-back datasets --undo ``` ### `idyl filesystem restore` Publish a saved Filesystem version as a new version, preserving intervening history. Name a saved version as v2, or use its saved-version name. The command waits for publication; a running writer may apply it afterwards. A Filesystem operand is its name, or its ID in the canonical form (lowercase 8-4-4-4-12 hexadecimal), which addresses the Filesystem by ID. \--idempotency-key identifies this request. Reuse the same key and version selector after an uncertain response. When omitted, the CLI chooses a key and reports it if the wait is interrupted. Ctrl-C stops waiting without cancelling the recorded operation. #### Usage ```bash theme={null} idyl filesystem restore [flags] ``` #### Flags | Flag | Description | | - | - | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | #### Examples ```bash theme={null} idyl filesystem restore datasets v2 idyl filesystem restore datasets before-cleanup -o json ``` ### `idyl filesystem trash` List the branches of a Filesystem's history in Trash, each with its Trash ID, the branch, its entry and version counts, when it was moved to Trash, and when it is deleted forever. A Filesystem operand is its name, or its ID in the canonical form (lowercase 8-4-4-4-12 hexadecimal), which addresses the Filesystem by ID. \--restore \ brings a branch back, with its tip unchanged, and waits until it is back. --delete \ deletes a branch forever: its entries, versions, command output and every stored object only they reach are removed, and the command waits until the removal is complete. Delete forever cannot be undone and asks for confirmation unless --yes is given. \--limit requests a page size, and --continue resumes a listing with the value the previous page returned. JSON and YAML preserve the server's envelope; \--restore prints the Trash entry and --delete the deletion. #### Usage ```bash theme={null} idyl filesystem trash [flags] ``` #### Flags | Flag | Description | | - | - | | `--continue ` | Opaque continuation value returned by the previous page. | | `--delete ` | Delete the branch with this Trash ID forever. | | `--idempotency-key ` | Stable request identity; reuse it with the same request after an uncertain response. | | `--limit ` | Maximum Trash entries in one page; the server chooses the default when omitted. Default: `0`. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--restore ` | Restore the branch with this Trash ID. | | `-y, --yes` | Skip confirmation prompts. | #### Examples ```bash theme={null} idyl filesystem trash datasets idyl filesystem trash datasets --restore 019ad9ba-7334-7eca-9958-9f00c6c9fc01 idyl filesystem trash datasets --delete 019ad9ba-7334-7eca-9958-9f00c6c9fc01 --yes ``` ### `idyl filesystem versions` List saved Filesystem versions, newest first. Version zero is the initial saved state. Version numbers are never reused. This command lists saved states; it does not save outstanding changes or change the current files. A Filesystem operand is its name, or its ID in the canonical form (lowercase 8-4-4-4-12 hexadecimal), which addresses the Filesystem by ID. \--name v41=before-cleanup gives a version a name, replacing its previous name. \--unname v41 removes its name. A name must be unique within the Filesystem; the server judges names. Naming returns the updated version instead of a list. \--branch selects a branch by its ID from 'idyl filesystem branches'. --limit requests a page size, and --continue resumes a listing with the opaque value the previous page returned. JSON and YAML preserve the server's listing envelope, including its continue value. #### Usage ```bash theme={null} idyl filesystem versions [flags] ``` #### Flags | Flag | Description | | - | - | | `--branch ` | Branch whose saved versions to list. | | `--continue ` | Opaque continuation value returned by the previous page. | | `--limit ` | Maximum versions in one page; the server chooses the default when omitted. Default: `0`. | | `--name ` | Name a saved version, as v41=before-cleanup. | | `-o , --output ` | Output format: table, json, yaml. Default: `table`. | | `--unname ` | Remove a saved version's name, as v41. | #### Examples ```bash theme={null} idyl filesystem versions datasets idyl filesystem versions datasets --continue -o json idyl filesystem versions datasets --name v41=before-cleanup idyl filesystem versions datasets --unname v41 ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.