Store and retrieve files on the ATmosphere (like Bluesky)
Written entirely in Bash Shell. No NodeJS here!
curl -sSL https://zio.sh/atfile/install.sh | bash
echo 'ATFILE_USERNAME="<your-atproto-username>"' > ~/.config/atfile.env # e.g. alice.bsky.social, did:plc:vdjlpwlhbnug4fnjodwr3vzh, did:web:twitter.com
echo 'ATFILE_PASSWORD="<your-atproto-password>"' >> ~/.config/atfile.env
atfile help- OS¹
- 🟡 Linux: GNU, MinGW and Termux only; musl² not supported
- 🟢 macOS: Compatible with built-in version of Bash (3.2)
- 🟡 Windows: MinGW (Cygwin, Git Bash, MSYS2, etc.) and WSL (see Linux caveats above)
- This repository does not provide a native version for Windows
- 🟢 BSD: FreeBSD, NetBSD and OpenBSD; other non-detected BSDs should work (see ¹)
- 🟢 Haiku: Yes, really
- 🔴 Solaris: Has issues; low priority
- Bash³: 3.x or later
- Packages
curl- ExifTool (
exiftool) (optional: setATFILE_SKIP_NI_EXIFTOOL=1to ignore) file(only on *BSD, macOS, or Linux)- GnuPG (
gpg) (optional: needed forupload-crypt,fetch-crypt) jq- MediaInfo (
mediainfo) (optional: setATFILE_SKIP_NI_MEDIAINFO=1to ignore) md5sum(optional: setATFILE_SKIP_NI_MD5SUM=1to ignore)- Both GNU and BusyBox versions supported
websocat(optional: needed forstream)
- ATProto account
- Both Bluesky PBC-operated and self-hosted accounts supported
- If you're using a
bsky.network(@*.bsky.social) account, limit the amount of files you upload to Bluesky PBC's servers. Heed the copyright warning: do not upload copyrighted files. did:webaccounts supported!
- If you're using a
- Confirmed to work on Bluesky PDS and millipds
- Other PDSs remain untested, but if they implement standard
com.atproto.*endpoints, there should be no reason these won't work - Filesize limits cannot be automatically detected. By default, this is 100MB
- To change this on Bluesky PDS, set
PDS_BLOB_UPLOAD_LIMIT=<bytes> - If the PDS is running behind Cloudflare, the Free plan imposes a 100MB upload limit
- This tool, nor setting a higher filesize limit, does not workaround video upload limits on Bluesky. Videos are served via a CDN, and adding larger videos to post records yields errors
- To change this on Bluesky PDS, set
- Other PDSs remain untested, but if they implement standard
- Both Bluesky PBC-operated and self-hosted accounts supported
There are three ways of installing ATFile. Either:
curl -sSL https://zio.sh/atfile/install.sh | bash
This will automatically fetch the latest version of ATFile and install it in an appropriate location, as well as creating a blank configuration file. Once downloaded and installed, the locations used will be output. They are as follows:
- Linux/Windows/BSD/Solaris
- Install:
$HOME/.local/bin/atfile- As
sudo/root:/usr/local/bin/atfile
- As
- Config:
$HOME/.config/atfile.env
- Install:
- macOS
- Install:
$HOME/.local/bin/atfile- As
sudo/root:/usr/local/bin/atfile
- As
- Config:
$HOME/Library/Application Support/atfile.env
- Install:
- Haiku
- Install:
/boot/system/non-packaged/bin/atfile - Config:
$HOME/config/settings/atfile.env$HOMEis always/homeon Haiku
- Install:
If $XDG_CONFIG_HOME is set, this will overwrite the config directory (e.g. setting XDG_CONFIG_HOME=$HOME/.local/share/atfile will result in the config being stored at $HOME/.local/share/atfile/atfile.env).
Custom config paths are supported, but set after-the-fact — see Manually below.
To install manually, see tags on @zio.sh/atfile, and download the required version under Artifacts. This can be stored and run from anywhere (and is identical to the version curl|bash fetched — this installed version can also be moved to custom locations at whim).
Don't forget to mark as executable with chmod +x atfile.sh. It's also a good idea to remove the version from the filename, as ATFile can update itself (with atfile update) and will overwrite the file (this functionality can be disabled with ATFILE_DISABLE_UPDATER=1).
Config locations are identical to those above (see Automatic ("curl|bash") above). To use a custom path, set $ATFILE_PATH_CONF. Variables can also be used (and overridden) with exports — see atfile help ➔ Environment Variables for more.
If you've pulled this repository, you can also use ATFile by simply calling ./atfile.sh — it functions just as a regular compiled version of ATFile, including reading from the same config file. Debug messages are turned on by default: disable these by setting ATFILE_DEBUG=0.
To compile, run ./atfile.sh build. The built version will be available at ./bin/atfile-<version>[+git.<hash>].sh.
Using a development version against your ATProto account could potentially inadvertently damage records.
See atfile help.
(Todo)
Development mainly takes place on Tangled, with GitHub acting as a mirror. If possible, please use Tangled for your contributions: since it is powered by ATProto, you can log in using your Bluesky account.
When submitting Pull Requests, target the dev branch: main is the current stable production version, and PRs will be rejected targeting this branch.
- Paul Frazee — 🦋 @pfrazee.com
His kind words - Laurens Hof — 🦋 @laurenshof.online
Featuring ATFile on The Fediverse Report: "Last Week in the ATmosphere – Oct 2024 week 4" - Samir — 🐙 @bdotsamir
Testing, and diagnosing problems with, support for macOS (macos) - Astra — 🦋 @astra.blue
Various PRs; testing, and diagnosing problems with, support for MinGW (linux-mingw) and Termux (linux-termux). - (Forgot about you? You know what to do)
- ¹ You can bypass OS detection in one of two ways:
- Set
ATFILE_SKIP_UNSUPPORTED_OS=1
Be careful! There's a reason some OSes are not supported - Set
ATFILE_FORCE_OS=<os>
This overrides the OS detected. Possible values:- BSD:
bsd-freebsd,bsd-netbsd,bsd-openbsd - Linux:
linux,linux-mingw,linux-musl,linux-termux - Other:
haiku,macos,solaris
- BSD:
- Set
- ² musl-powered distros do not use GNU/glibc packages, and have problems currently
- Known musl distros: Alpine, Chimera, Dragora, Gentoo (musl), Morpheus, OpenWrt, postmarketOS, Sabotage, Void
- Bypassing OS detection (see ¹) will work, but dates will not be handled correctly
- ³ As long as you have Bash installed, running from another shell will not be problematic (
#!/usr/bin/env bashforces Bash)