atfile

ATFile

Store and retrieve files on the ATmosphere (like Bluesky or Tangled)
Written entirely in Bash Shell. No NodeJS here!

✨ Quick Start

curl -sSL https://zio.sh/atfile.sh | bash
echo 'ATFILE_USERNAME="<your-atproto-username>"' > ~/.config/atfile.env # e.g. alice.bsky.social, did:plc:wshs7t2adsemcrrd4snkeqli, did:web:zio.sh
echo 'ATFILE_PASSWORD="<your-atproto-password>"' >> ~/.config/atfile.env
atfile help

👀 Detailed Usage

✅ Requirements

• OS¹
  • 🟡 Linux: GNU, MinGW and Termux only; musl² not supported
  • 🟢 macOS: Compatible with built-in version of Bash (3.2)
  • 🔴 Windows: No native version available
    • Run with MinGW (Cygwin, Git Bash, MSYS2, etc.) or WSL (see Linux caveats above)
  • 🟢 *BSD: FreeBSD, NetBSD, OpenBSD, and other *BSD's
  • 🟢 Haiku: Yes, really
  • 🔴 Solaris: Has issues; low priority
  • 🔴 SerenityOS: Untested
• Bash³: 3.x or later
• Packages
  • curl
  • ExifTool (exiftool) (optional: set ATFILE_DISABLE_NI_EXIFTOOL=1 to ignore)
  • file (only on *BSD, macOS, or Linux)
  • GnuPG (gpg) (optional: needed for upload-crypt, fetch-crypt)
  • jq
  • MediaInfo (mediainfo) (optional: set ATFILE_DISABLE_NI_MEDIAINFO=1 to ignore)
  • md5sum (optional: set ATFILE_DISABLE_NI_MD5SUM=1 to ignore)
    • Both GNU and BusyBox versions supported
  • websocat (optional: needed for stream)
• ATProto account
  • Limit the amount of files you upload, and avoid copyrighted files, if using a managed PDS
    (e.g. Blacksky, Bluesky, Spark, Tangled, or any other independent PDS you don't own)
  • Supports accounts with did:plc and did:web identities
  • Supports PDSs running 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

⬇️ Downloading & Installing

There are three ways of installing ATFile. Either:

Automatic ("curl|bash")

curl -sSL https://zio.sh/atfile.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/*BSD/Solaris/SerenityOS
  • Install: $HOME/.local/bin/atfile
    • As sudo/root: /usr/local/bin/atfile
  • Config: $HOME/.config/atfile.env, or $XDG_CONFIG_HOME/atfile.env (if set)
• macOS
  • Install: $HOME/.local/bin/atfile
    • As sudo/root: /usr/local/bin/atfile
  • Config: $HOME/Library/Application Support/atfile.env
• Haiku
  • Install: /boot/system/non-packaged/bin/atfile
  • Config: $HOME/config/settings/atfile.env

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. Consider renaming to atfile.sh (as ATFile can update itself, making a fixed version in the filename nonsensical), and mark as executable (with chmod +x atfile.sh).

Config locations are identical to those above (see Automatic ("curl|bash") above).

Repository

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.

Config locations are identical to those above (see Automatic ("curl|bash") above).

Using a development version against your ATProto account could potentially inadvertently damage records.

⌨️ Using

See atfile help.

🏗️ Building

To compile, run ./atfile.sh build. The built version will be available at ./bin/atfile-<version>[+git.<hash>].sh.

Environment variables

Various environment variables can be exported to control various aspects of the development version. These are as follows:

• ATFILE_DEVEL_ENABLE_PIPING <int> (default: 0)
  Allow piping (useful to test installation) (e.g. cat ./atfile.sh | bash)
• ATFILE_DEVEL_ENABLE_PUBLISH <int> (default: 0)
  Publish build to ATProto repository (to allow for updating) as the last step when running release. Several requirements must be fulfilled to succeed:
  • ATFILE_DEVEL_DIST_USERNAME must be set
    By default, this is set to $did in atfile.sh (see 🏗️ Building ➔ Meta). Ideally, you should not set this variable as updates in the built version will not be fetched from the correct place
  • ATFILE_DEVEL_DIST_PASSWORD must be set
  • No tests should return an Error (Warning is acceptable)
  • Git commit must be tagged

Other ATFILE_DEVEL_ environment variables are visible in the codebase, but these are computed internally and cannot be set/modified.

Directives

Various build directives can be set in files to control various aspects of the development version. These are set with # atfile-devel= directive at the top of the file, using commas to separate values. These are as follows:

• ignore-build
  Do not include file in the final compiled build

Meta

Various meta variables can be set to be available in the final compiled build (usually found in help). These are found in atfile.sh under # Meta. These variables are as follows:

• author <string>
  Copyright author
• did <did>
  DID of copyright author. Also used as the source for published builds, unless ATFILE_DEVEL_DIST_USERNAME is set (see 🏗️ Building ➔ Environment variables)
• repo <uri>
  Repository URL of source code
• version <string>
  Version in the format of <major>.<minor>[.<patch>]. Not following this format will cause unintended issues. Git hashes (+git.abc1234) are added automatically during build when a git tag is not applied to the current commit
• year <int>
  Copyright year

⌨️ Contributing

Development takes place on Tangled (@zio.sh/atfile), with GitHub (ziodotsh/atfile) acting as a mirror. Use Tangled for your contributions, for both Issues and Pulls. As Tangled is powered by ATProto, you already have an account (unsure? Try logging in with your Bluesky handle).

When submitting Pulls, target the dev branch: main is the current stable production version, and Pulls will be rejected targeting this branch.

🤝 Acknowledgements

• 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_DISABLE_UNSUPPORTED_OS_WARN=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, haiku, linux, linux-mingw, linux-musl, linux-termux, macos, serenity, and solaris.
• ² 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 cause unintended behavior
• ³ As long as you have Bash installed, running from another shell will not be problematic (#!/usr/bin/env bash forces Bash)