idyl filesystem - IDYL Docs

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

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 <string>, --account-id <string>`	Account ID to use, overriding the current context.
`-c <string>, --context <string>`	Use the named context for this command.
`--homedir <string>`	Override the configuration directory. Defaults to ~/.config/idyl.
`-n <string>, --namespace <string>`	Namespace to address, overriding the entered context.
`--network <string>`	Override the Network for this command.
`-p <string>, --profile <string>`	Override the access profile for this command.
`-s <string>, --subnet <string>`	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 <branch-id>=<name> names a branch, and —unname <branch-id> removes its name; names are unique within the Filesystem. —trash <branch-id> 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

idyl filesystem branches <name> [flags]

Flags

Flag	Description
`--continue <string>`	Opaque continuation value returned by the previous page.
`--idempotency-key <string>`	Stable request identity; reuse it with the same request after an uncertain response.
`--limit <uint>`	Maximum branches in one page; the server chooses the default when omitted. Default: `0`.
`--name <string>`	Name a branch, as <branch-id>=<name>.
`-o <string>, --output <string>`	Output format: table, json, yaml. Default: `table`.
`--trash <string>`	Move a branch to Trash.
`--unname <string>`	Remove a branch’s name.

Examples

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

idyl filesystem commit <name> [flags]

Flags

Flag	Description
`--idempotency-key <string>`	Stable request identity; reuse it with the same request after an uncertain response.
`-o <string>, --output <string>`	Output format: table, json, yaml. Default: `table`.

Examples

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

idyl filesystem cp <src> <dst> [flags]

Flags

Flag	Description
`--idempotency-key <string>`	Stable request identity; reuse it with the same request after an uncertain response.
`-o <string>, --output <string>`	Output format: table, json, yaml. Default: `table`.
`--save-first`	Save current files before a download; cannot be combined with @version.

Examples

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 <filesystem>@<version> 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

idyl filesystem create <name> [flags]

Flags

Flag	Description
`--fork-of <string>`	Create as a copy of a saved version, as datasets@v12.
`--headroom <string>`	Requested reservation for outstanding changes, such as 2Gi.
`--idempotency-key <string>`	Stable request identity; reuse it with the same request after an uncertain response.
`-o <string>, --output <string>`	Output format: table, json, yaml. Default: `table`.
`--size <string>`	Requested size, such as 10Gi.
`--store <string>`	Admitted Store name; fixed after creation.

Examples

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

idyl filesystem delete <name> [flags]

Aliases

rm

Flags

Flag	Description
`-o <string>, --output <string>`	Output format: table, json, yaml. Default: `table`.
`-y, --yes`	Skip confirmation prompts.

Examples

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

idyl filesystem edit <name> [flags]

Flags

Flag	Description
`-o <string>, --output <string>`	Output format: table, json, yaml. Default: `table`.
`--set-headroom <string>`	Requested reservation for outstanding changes, such as 8Gi.
`--set-size <string>`	Requested size, such as 100Gi.

Examples

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 <path> and —rename <from>=<to> 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

idyl filesystem files <name>[@version][:path] [flags]

Flags

Flag	Description
`--continue <string>`	Opaque continuation value returned by the previous page.
`--delete <stringArray>`	Delete a saved path in the new version; repeat for more.
`--idempotency-key <string>`	Stable request identity; reuse it with the same request after an uncertain response.
`--limit <uint>`	Maximum entries in one page; the server chooses the default when omitted. Default: `0`.
`-o <string>, --output <string>`	Output format: table, json, yaml. Default: `table`.
`--rename <stringArray>`	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

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

idyl filesystem fork <name>@<version> <new> [flags]

Flags

Flag	Description
`--idempotency-key <string>`	Stable request identity; reuse it with the same request after an uncertain response.
`-o <string>, --output <string>`	Output format: table, json, yaml. Default: `table`.

Examples

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

idyl filesystem get [name] [flags]

Aliases

list
ls

Flags

Flag	Description
`-A, --all-namespaces`	List across every namespace in the account.
`--continue <string>`	Opaque continuation value returned by the previous page.
`--limit <uint>`	Maximum filesystems in one page; the server chooses the default when omitted. Default: `0`.
`-o <string>, --output <string>`	Output format: table, json, yaml. Default: `table`.

Examples

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

idyl filesystem go-back <name> [version|version-name|entry-id] [flags]

Flags

Flag	Description
`--idempotency-key <string>`	Stable request identity; reuse it with the same request after an uncertain response.
`-o <string>, --output <string>`	Output format: table, json, yaml. Default: `table`.
`--undo`	Return to where the last go-back left.

Examples

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

idyl filesystem restore <name> <version|version-name> [flags]

Flags

Flag	Description
`--idempotency-key <string>`	Stable request identity; reuse it with the same request after an uncertain response.
`-o <string>, --output <string>`	Output format: table, json, yaml. Default: `table`.

Examples

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 <trash-id> brings a branch back, with its tip unchanged, and waits until it is back. —delete <trash-id> 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

idyl filesystem trash <name> [flags]

Flags

Flag	Description
`--continue <string>`	Opaque continuation value returned by the previous page.
`--delete <string>`	Delete the branch with this Trash ID forever.
`--idempotency-key <string>`	Stable request identity; reuse it with the same request after an uncertain response.
`--limit <uint>`	Maximum Trash entries in one page; the server chooses the default when omitted. Default: `0`.
`-o <string>, --output <string>`	Output format: table, json, yaml. Default: `table`.
`--restore <string>`	Restore the branch with this Trash ID.
`-y, --yes`	Skip confirmation prompts.

Examples

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

idyl filesystem versions <name> [flags]

Flags

Flag	Description
`--branch <string>`	Branch whose saved versions to list.
`--continue <string>`	Opaque continuation value returned by the previous page.
`--limit <uint>`	Maximum versions in one page; the server chooses the default when omitted. Default: `0`.
`--name <string>`	Name a saved version, as v41=before-cleanup.
`-o <string>, --output <string>`	Output format: table, json, yaml. Default: `table`.
`--unname <string>`	Remove a saved version’s name, as v41.

Examples

idyl filesystem versions datasets
idyl filesystem versions datasets --continue <value> -o json
idyl filesystem versions datasets --name v41=before-cleanup
idyl filesystem versions datasets --unname v41

​Usage

​Aliases

​Commands

​Inherited flags

​Subcommand reference

​idyl filesystem branches

​Usage

​Flags

​Examples

​idyl filesystem commit

​Usage

​Flags

​Examples

​idyl filesystem cp

​Usage

​Flags

​Examples

​idyl filesystem create

​Usage

​Flags

​Examples

​idyl filesystem delete

​Usage

​Aliases

​Flags

​Examples

​idyl filesystem edit

​Usage

​Flags

​Examples

​idyl filesystem files

​Usage

​Flags

​Examples

​idyl filesystem fork

​Usage

​Flags

​Examples

​idyl filesystem get

​Usage

​Aliases

​Flags

​Examples

​idyl filesystem go-back

​Usage

​Flags

​Examples

​idyl filesystem restore

​Usage

​Flags

​Examples

​idyl filesystem trash

​Usage

​Flags

​Examples

​idyl filesystem versions

​Usage

​Flags

​Examples

Usage

Aliases

Commands

Inherited flags

Subcommand reference

`idyl filesystem branches`

Usage

Flags

Examples

`idyl filesystem commit`

Usage

Flags

Examples

`idyl filesystem cp`

Usage

Flags

Examples

`idyl filesystem create`

Usage

Flags

Examples

`idyl filesystem delete`

Usage

Aliases

Flags

Examples

`idyl filesystem edit`

Usage

Flags

Examples

`idyl filesystem files`

Usage

Flags

Examples

`idyl filesystem fork`

Usage

Flags

Examples

`idyl filesystem get`

Usage

Aliases

Flags

Examples

`idyl filesystem go-back`

Usage

Flags

Examples

`idyl filesystem restore`

Usage

Flags

Examples

`idyl filesystem trash`

Usage

Flags

Examples

`idyl filesystem versions`

Usage

Flags

Examples