{"id":18608505,"url":"https://github.com/earthstar-project/earthstar-cli","last_synced_at":"2025-04-10T22:30:49.217Z","repository":{"id":42389909,"uuid":"266911179","full_name":"earthstar-project/earthstar-cli","owner":"earthstar-project","description":"A complete Earthstar toolbox in the console.","archived":false,"fork":false,"pushed_at":"2023-01-02T12:17:07.000Z","size":168,"stargazers_count":12,"open_issues_count":13,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-05-23T00:23:33.483Z","etag":null,"topics":["cli","deno","distributed","earthstar"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/earthstar-project.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":"2020-05-26T00:55:18.000Z","updated_at":"2024-01-20T04:41:10.000Z","dependencies_parsed_at":"2023-02-01T02:45:30.309Z","dependency_job_id":null,"html_url":"https://github.com/earthstar-project/earthstar-cli","commit_stats":null,"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthstar-project%2Fearthstar-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthstar-project%2Fearthstar-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthstar-project%2Fearthstar-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthstar-project%2Fearthstar-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/earthstar-project","download_url":"https://codeload.github.com/earthstar-project/earthstar-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246811766,"owners_count":20837833,"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","deno","distributed","earthstar"],"created_at":"2024-11-07T03:03:13.205Z","updated_at":"2025-04-10T22:30:48.881Z","avatar_url":"https://github.com/earthstar-project.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Earthstar CLI\n\n\u003e ### **🚨🚨🚨 The Earthstar CLI is not under active development**! Please check out [user-scripts](https://github.com/earthstar-project/user_scripts) instead, which offers pretty much all of the same functionality as the CLI, but with the benefit that you can extend functionality with your own scripts, and tweak existing ones. \n\n---\n\nA complete command-line suite for everything Earthstar. Manage identities, back\nup shares on your computer, and sync with replica servers over the internet.\n\n- `earthstar identities` - Generate and manage Earthstar identities.\n- `earthstar shares` - Create, sync, and interact with shares.\n- `earthstar servers` - Add and remove replica servers you want to sync with.\n- `earthstar upgrade` - Upgrade the CLI to the latest version.\n\nThis tool also provides a special filesystem synchronisation feature, allowing\nyou to use your filesystem as a way to view and modify share data. More on that\nbelow!\n\n## Installation\n\nIn time we will have pre-compiled binaries of this tool. Until then, you'll need\nto have Deno installed\n([instructions here](https://deno.land/manual/getting_started/installation)).\n\n\u003e If you had the previous Node version of the CLI installed, make sure to\n\u003e uninstall it using `npm uninstall -g earthstar-cli`.\n\nOnce Deno is installed, run the following command in your terminal:\n\n`deno install --allow-read --allow-write --allow-net --allow-run --allow-env --no-check --unstable -f --location https://earthstar-project.org -n earthstar https://deno.land/x/earthstar_cli/src/main.ts`\n\nThere are a few permission flags there. Here is what they are for:\n\n- `--allow-read` - Reading Earthstar databases on the filesystem, filesystem\n  sync.\n- `--allow-write` - Writing Earthstar databases to the filesystem, filesystem\n  sync.\n- `--allow-net` - Synchronising with remote servers, checking for latest CLI\n  version.\n- `--allow-run` - Running the upgrade script.\n- `--allow-env` - Gets your HOME path when suggesting where to store your\n  shares.\n\nYou will see a message once installation is complete.\n\n\u003e If you ever want to uninstall, run `deno uninstall earthstar`.\n\n## `earthstar identities`\n\nCreate new Earthstar identities or save existing ones, as well as set a current\nidentity which is used by default for commands which write data to shares.\n\n- `list` - List all saved identities.\n- `switch` - Switch the identity used by default for setting data.\n- `generate \u003cshortname\u003e` - Generate a new identity with a shortname.\n- `add \u003caddress\u003e \u003csecret\u003e` - Manually add an existing identity with a address\n  and secret.\n- `remove` - Forget an identity.\n- `info` - Display an identity's public address and/or secret.\n\nExtra flags can be found for each of these commands by using the `--help` flag.\n\n## `earthstar shares`\n\nManage, create, modify, and sync your Earthstar shares. Take it one step\nfurther, and view and modify their contents through your filesystem!\n\nYour shares are saved locally as Sqlite databases in a directory of your choice,\nmaking them fully functional even when you're offline.\n\n- `generate \u003cname\u003e` - Generate a new share address using a shortname you\n  provide.\n- `add \u003cshareAddress\u003e` - Add an existing share using its public address.\n- `list` - List all known shares.\n- `remove` - Forget a known share.\n- `set` - Write data to a path on a share.\n- `paths` - List all document paths on a share.\n- `latest` - Display the latest document at a given path.\n- `contents` - Get the latest content at a given path.\n- `sync` - Sync your shares with known replica servers OR a local share\n  database.\n- `sync-files` - Bidirectionally synchronise a share's documents with a\n  directory on your filesystem.\n- `set-share-dir` - Set the filesystem directory where your share data is\n  stored.\n\nExtra flags can be found for each of these commands by using the `--help` flag.\n\n## `earthstar servers`\n\nManage a list of replica servers you know and trust, and which will be synced\nwith when you run `earthstar shares sync`.\n\nEven if you have many shares, replica servers will only have knowledge of those\nthey knew of beforehand. Your shares will never be leaked to replica servers\nthat don't know about them already.\n\n- `list` - List known replica servers\n- `add \u003curl\u003e` - Add a replica server by its URL.\n- `remove` - Forget a replica server.\n\nExtra flags can be found for each of these commands by using the `--help` flag.\n\n## Filesystem synchronisation\n\n`earthstar shares sync-files` synchronises a share with a directory,\nrepresenting a share's documents as files on your computer. If you modify those\nfiles, those modifications can be synchronised _back_ to the share, and synced\nwith other peers!\n\nThis makes it possible for you to interact with share documents with the tools\nyou already know and use.\n\n- Synchronise a knowledgebase of markdown files across different machines and\n  users (e.g. Obsidian)\n- Create websites with your friends (and serve it from one of your replica\n  servers!)\n- Start a sneakernet of funny images you pass by USB key, synced from one\n  computer to the next.\n\nThere are some caveats:\n\n- **Earthstar's current maximum size for documents is 4 megabytes**. If you try\n  to sync a document larger than this, sync will throw a warning. This limit\n  will be addressed in the near future.\n- Binary files will be encoded to base64, increasing their size by ~30%. This\n  will also be addressed in the near future.\n- Writing to certain 'owned' paths may not be permitted, throwing an error when\n  you try to sync. If you don't care about losing the local data, you can use\n  the `--overwriteFilesAtOwnedPaths` flag.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fearthstar-project%2Fearthstar-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fearthstar-project%2Fearthstar-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fearthstar-project%2Fearthstar-cli/lists"}