{"id":21331559,"url":"https://github.com/lukechampine/user","last_synced_at":"2025-07-12T10:30:50.444Z","repository":{"id":46798836,"uuid":"188907774","full_name":"lukechampine/user","owner":"lukechampine","description":"A CLI renter for Sia","archived":false,"fork":false,"pushed_at":"2021-09-25T02:20:29.000Z","size":99,"stargazers_count":12,"open_issues_count":14,"forks_count":2,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-06-20T16:32:48.291Z","etag":null,"topics":["cli","cloud-storage","fuse","http-server","sia"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lukechampine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-27T20:52:09.000Z","updated_at":"2022-10-29T06:20:33.000Z","dependencies_parsed_at":"2022-09-07T17:11:08.937Z","dependency_job_id":null,"html_url":"https://github.com/lukechampine/user","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukechampine%2Fuser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukechampine%2Fuser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukechampine%2Fuser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukechampine%2Fuser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lukechampine","download_url":"https://codeload.github.com/lukechampine/user/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225814913,"owners_count":17528295,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cloud-storage","fuse","http-server","sia"],"created_at":"2024-11-21T22:42:22.348Z","updated_at":"2024-11-21T22:42:22.881Z","avatar_url":"https://github.com/lukechampine.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# user\n\n`user` is a CLI renter for Sia. It is an alternative to `siad`'s renter module.\nThe biggest difference is that `user` is a program that you invoke to perform\nspecific actions, whereas `siad` is a daemon that runs continuously in the\nbackground. The other major difference is that `siad` manages your contracts for\nyou by select good hosts, maintaining a pool of usuable contracts, and\nautomatically renewing contracts when necessary. `user`, by contrast, offloads\nthese responsibilities to a [`muse`](https://github.com/lukechampine/muse)\nserver.\n\n`user` provides some functionality that `siad` does not. It allows you to upload\nand download with having to run a full node; it efficiently stores small files;\nit makes it easy to share files with your friends; and more. On the other hand,\nsince `user` does not run in the background, it cannot automatically repair your\nfiles like `siad` does.\n\n\n## Setup\n\nFirst you'll need to install `user` by checking out this repository and running\n`make`. Run `user version` to confirm that it's installed.\n\n`user` cannot operate on its own; it needs contracts, which it gets from a\n[`muse`](https://github.com/lukechampine/muse) server. You can specify the\naddress of this server using a CLI flag, but it's more convenient to add it to\nyour [config file](#configuration).\n\n\n## Uploading and Downloading Files\n\n`user` stores and retrieves files using *metafiles*, which are small files\ncontaining the metadata necessary to retrieve and modify a file stored on a\nhost. Uploading a file creates a metafile, and downloading a metafile creates a\nfile. Metafiles can be downloaded by anyone possessing contracts with the file's\nhosts. You can share a metafile simply by sending it; to share multiple files,\nbundle their corresponding metafiles in an archive such as a `.tar` or `.zip`.\n\nNote that metafiles represent \"snapshots\" of a file at a particular time; if you\nshare a metafile, and then modify your copy, the recipient will not see your\nmodifications. Likewise, if the recipient modifies their copy, it will not\naffect your own.\n\nThe upload and download commands are straightforward:\n\n```\n$ user upload [file] [metafile]\n\n$ user download [metafile] [file]\n```\n\n`file` is the path of the file to be read (during upload) or written (during\ndownload), and `metafile` is the path where the file metadata will be written.\nThe extension for metafiles is `.usa` (`a` for \"archive\"). If you omit the final\nargument, the name of the file or metafile is chosen automatically (by either\nremoving or appending the `.usa` extension).\n\nWhen uploading, you must specify the desired redundancy of the file, which you\ncan do by passing the `-m` flag or by setting the `min_shards` value in your\n[config file](#configuration). This value refers to the minimum number of hosts\nthat must be reachable for you to download the file. For example, if you have 10\ncontracts, and you upload with `-m 5`, you will be able to download as long as\nany 5 hosts are reachable. The redundancy of the file in this example is 2x.\n\nThe `upload` command erasure-encodes `file` into \"shards,\" encrypts each shard\nwith a different key, and uploads one shard to each host. The `download` command\nis the inverse: it downloads shards from each host, decrypts them, and joins the\nerasure-encoded shards back together, writing the result to `file`.\n\nUploads and downloads are resumable. If `metafile` already exists when starting\nan upload, or if `file` is smaller than the target filesize when starting a\ndownload, then these commands will pick up where they left off.\n\nYou can also upload or download multiple files by specifying a directory path\nfor both `file` and `metafile`. The directory structure of the metafiles will\nmirror the structure of the files. This variant is strongly recommended when\nuploading many small files, because it allows `user` to pack multiple files\ninto a single 4MB sector, which saves lots of bandwidth and money. (Normally,\neach uploaded file must be padded to 4MB.)\n\nIt is also possible to redirect a download command:\n\n```\n$ user download [metafile] | wc -l\n```\n\nThis means you can pipe downloaded files directly into other commands without\ncreating a temporary file.\n\n\n## Migrating Files\n\nWhen metafiles have a redundancy greater than 1x, they can still be downloaded\neven if some of their hosts are unreachable. But if too many hosts become\nunreachable, the metafile will be lost. For this reason, it is prudent to\nre-upload your metafiles to better hosts if they are at risk of being lost.\nIn `us`, this process is called \"migration.\"\n\nIf you have a local copy of the original file, you can re-upload it to the new\nhosts immediately. If you don't have a local copy, you must download the file\nfirst, then re-upload it to the new hosts. In `user`, these options are called\n`file` and `remote`, respectively.\n\nLet's assume that you uploaded a file to three hosts with `min_shards = 2`, and\none of them is now unresponsive. You would like to repair the missing redundancy\nby migrating the shard on the unresponsive host to a new host. If you had a copy\nof the original file, you could run:\n\n```\n$ user migrate -file=[file] [metafile]\n```\n\nUnfortunately, in this example, you do not have the original file. However,\nthere are still two good hosts available, so you can download their shards and\nuse them to reconstruct the third shard by running:\n\n```\n$ user migrate -remote [metafile]\n```\n\nNote that in a remote migration, the file is not actually downloaded to disk; it\nis processed piecewise in RAM. You don't need any free disk space to perform a\nmigration.\n\nLike uploads and downloads, migrations can be resumed if interrupted, and can\nalso be applied to directories.\n\n\n## Configuration\n\n`user` can be configured via a file named `~/.config/user/config.toml`:\n\n```toml\n# API address of muse server.\n# REQUIRED.\nmuse_addr = \"muse.lukechampine.com/\u003cmy-muse-id\u003e\"\n\n# API address of SHARD server.\n# OPTIONAL. If not provided, the muse server will be used instead.\nshard_addr = \"shard.lukechampine.com\"\n\n# Minimum number of hosts required to download a file. Also controls\n# file redundancy: uploading to 40 hosts with min_shards = 10 results\n# in 4x redundancy.\n# REQUIRED (unless the -m flag is passed to user).\nmin_shards = 10\n```\n\n\n## Extras\n\n### Uploading and Downloading with FUSE\n\nFUSE is a technology that allows you to mount a \"virtual filesystem\" on your\ncomputer. The `user` FUSE filesystem behaves like a normal folder, but behind\nthe scenes, it is transferring data to and from Sia hosts. You can upload a file\nsimply by copying it into the folder, or download by opening a file within the\nfolder.\n\nThe command to mount the virtual filesystem is:\n\n```\n$ user mount [metadir] [mnt]\n```\n\n`metadir` is the directory where metafiles will be written and read. Each such\nmetafile will correspond to a virtual file in the `mnt` directory. For example,\nif you create `bar/foo.txt` in `mnt`, then `bar/foo.txt.usa` will appear in\n`metadir`.\n\nUnlike most `user` commands, `mount` will remain running until you stop it with\nCtrl-C. Don't kill it suddenly (e.g. by turning off your computer) or you will\nalmost certainly lose data. If you do experience an unclean shutdown, you may\nencounter errors accessing the folder later. To fix this, run `fusermount -u`\non the `mnt` directory to forcibly unmount it.\n\n\n### Downloading over HTTP\n\n`user` can serve a directory of metafiles over HTTP with the `serve` command:\n\n```\n$ user serve [metadir]\n```\n\nYou can then browse to http://localhost:8080 to view the files in your web\nbrowser.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukechampine%2Fuser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukechampine%2Fuser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukechampine%2Fuser/lists"}