Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/valeriangalliat/firefox-sync-cli
Manage Firefox Sync from the CLI! ✨
https://github.com/valeriangalliat/firefox-sync-cli
Last synced: 25 days ago
JSON representation
Manage Firefox Sync from the CLI! ✨
- Host: GitHub
- URL: https://github.com/valeriangalliat/firefox-sync-cli
- Owner: valeriangalliat
- Created: 2021-10-16T13:05:59.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2023-05-16T19:51:43.000Z (over 1 year ago)
- Last Synced: 2024-10-14T07:53:07.635Z (about 1 month ago)
- Language: JavaScript
- Homepage:
- Size: 14.6 KB
- Stars: 8
- Watchers: 4
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Firefox Sync CLI [](https://www.npmjs.org/package/firefox-sync-cli)
> Manage Firefox Sync from the CLI! ✨
## Overview
Firefox Sync is a great tool, but up to now, there was no easy way to
interact with it programmatically, or a command line interface to access
the data it holds (like bookmarks, history, or Lockwise passwords).
Using [Node Firefox Sync](https://github.com/valeriangalliat/node-firefox-sync),
this CLI gives you access to all the endpoints and objects exposed by
the [Firefox Sync API](https://mozilla-services.readthedocs.io/en/latest/storage/apis-1.5.html).
It features two ways to authenticate, one using a Firefox Accounts email
and password to open a session, and one using OAuth. See more about them
[below](#authentication).
## Installation
```sh
npm install -g firefox-sync-cli
```
The command will be available as `ffs`. 😏
## Usage
```
Usage: ffs [options] [command]
Options:
--version Show version.
-c, --creds File to get Firefox Sync creds from (or
write to during authentication and
refresh).
-v, --verbose Output more details.
-h, --help Show this screen.
Commands:
auth [email] [password] Sign in using email and password.
oauth Sign in using OAuth.
collections List available collections.
get [options] [id...] Get some or all items from a collection.
When getting all items, pass '--full' to
get the full objects.
set Store one or multiple payloads from
'stdin' in the given collection.
delete Delete the given items by ID.
quota Get the current usage and storage quota.
collection-usage Get the usage in kB of all collections.
collection-counts Get the number of items in each
collection.
configuration Get the storage server configuration.
help [command] Display help for command.
```
A typical flow will look like this:
```sh
ffs -c ~/.ffs-creds.json oauth
ffs -c ~/.ffs-creds.json collections
ffs -c ~/.ffs-creds.json get bookmarks --full
```
During authentication, this will create `~/.ffs-creds.json` to store the
credentials necessary to access Firefox Sync.
Further commands read credentials from this file to use that session to
query the API.
## Authentication
### Email and password
This opens a session with full access to the given Firefox Account in
order to get the credentials to access Firefox Sync.
By design, this means this program will have to access to your plaintext
password. It doesn't store it, and just forwards it to [fxa-js-client](https://www.npmjs.com/package/fxa-js-client)
which handles the actual authentication.
### OAuth
You're given a OAuth URL to open in your browser, where you can input
your password in Mozilla's own website, which will in turn grant access
to this program by redirecting to a URL that includes an authentication
code.
With this method, the program never gets access to the plaintext
password, on top of being granted a token with restricted permissions.
That said there's [currently no way](https://www.codejam.info/2021/08/scripting-firefox-sync-lockwise-complete-oauth.html#a-note-about-granular-scopes)
to request access to specific Firefox Sync collections meaning that this
grant will have access to all the native Firefox Sync collections.
Because this program doesn't have its own OAuth client ID, it uses the
public client ID from the [Lockwise Android app](https://github.com/mozilla-lockwise/lockwise-android/blob/d3c0511f73c34e8759e1bb597f2d3dc9bcc146f0/app/src/main/java/mozilla/lockbox/support/Constant.kt#L29%3E).
This means that we don't control the OAuth redirect URL, and can't set
it to a temporary server on some random `localhost` port, which would
allow seamless authentication of this CLI. To work around that, the CLI
will kindly ask you to open the OAuth URL in Firefox, which it knows how
to poll for "visited places" by querying `places.sqlite` in the profile
directory. It will be able to detect the Android app redirect URL to
extract the OAuth code and complete the authentication process.
In case this doesn't work (it's clearly a hack, let's face it), consider
falling back to password authentication!
## See also
[Node Firefox Sync](https://github.com/valeriangalliat/node-firefox-sync),
the underlying client library that powers the CLI.
The story on how this all started when I tried to access my Lockwise
passwords from the CLI:
1. [A journey to scripting Firefox Sync / Lockwise: existing clients](https://www.codejam.info/2021/08/scripting-firefox-sync-lockwise-existing-clients.html)
1. [A journey to scripting Firefox Sync / Lockwise: figuring the protocol](scripting-firefox-sync-lockwise-figuring-the-protocol.html)
1. [A journey to scripting Firefox Sync / Lockwise: understanding BrowserID](scripting-firefox-sync-lockwise-understanding-browserid.html)
1. [A journey to scripting Firefox Sync / Lockwise: hybrid OAuth](scripting-firefox-sync-lockwise-hybrid-oauth.html)
1. [A journey to scripting Firefox Sync / Lockwise: complete OAuth](scripting-firefox-sync-lockwise-complete-oauth.html)