Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Mikescher/firefox-sync-client
A cli for firefox-sync (firefox bookmarks, passwords, account, ...)
https://github.com/Mikescher/firefox-sync-client
Last synced: 3 months ago
JSON representation
A cli for firefox-sync (firefox bookmarks, passwords, account, ...)
- Host: GitHub
- URL: https://github.com/Mikescher/firefox-sync-client
- Owner: Mikescher
- License: apache-2.0
- Created: 2022-08-24T19:15:54.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2024-06-22T19:43:28.000Z (5 months ago)
- Last Synced: 2024-06-23T21:53:45.439Z (5 months ago)
- Language: Go
- Size: 8.48 MB
- Stars: 72
- Watchers: 2
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
ffsclient - firefox-sync-client
===============================
A commandline-utility to list/view/edit/delete entries in a firefox-sync account.
Can be used to access bookmarks, passwords, forms, tabs, history or custom data.
[](https://asciinema.org/a/533143)
Table of contents
=================
* [Installation](#installation)
* [Usage](#usage)
* [Examples](#example)
* [Get all bookmarks as json](#get-all-bookmarks-as-json)
* [Get all bookmarks in netscape format (same as firefox bookmarks.html)](#get-all-bookmarks-in-netscape-format-same-as-firefox-bookmarkshtml)
* [Get a single bookmark](#get-a-single-bookmark)
* [Create a new bookmark](#create-a-new-bookmark)
* [List all passwords](#list-all-passwords)
* [List deleted passwords](#list-deleted-passwords)
* [Add a new password](#add-a-new-password)
* [Delete any record](#delete-any-record)
* [Query the server without a session file](#query-the-server-without-a-session-file)
* [Create and read unencrypted records](#create-and-read-unencrypted-records)
* [Delete a password](#manual)
* [Request Flowchart](#request-flowchart)
Installation
============
The latest binary (windows/linux/macOS/FreeBSD/OpenBSD) can be downloaded from the [github releases page](https://github.com/Mikescher/firefox-sync-client/releases):.
https://github.com/Mikescher/firefox-sync-client/releases/latest
ffsclient does not have any dependencies and can be placed directly in your $PATH (eg /usr/local/bin).
Alternatively you can use one of the following package manager:
- [Arch User Repository](https://aur.archlinux.org/packages/ffsclient): `yay -S ffsclient-git` / `yay -S ffsclient-bin`
- [Homebrew](https://formulae.brew.sh/formula/ffsclient): `brew tap Mikescher/tap && brew install ffsclient`
- [Chocolatey](https://community.chocolatey.org/packages/ffsclient): `choco install ffsclient`
Usage
=====
Before the first use you have to authenticate your client and create a session.
Call `ffsclient login {username} {password}` and a session will be created in `~/.config/firefox-sync-client.secret`
After this you can freely use ffsclient (see the full [Manual](#manual) for all commands).
Common commands are `ffsclient collections` to list all collections in the current account, `ffsclient list {collection}` to list all records in a collection and `ffsclient get {collection} {record-id}` to get a single record.
Almost all commands support different output-formats that can be specified with `--format {fmt}`, available are `text`, `json`, `xml`, `table`, `netscape`, `csv`, `tsv`. If no format is supplied the command uses a default.
You can get an overview of all commands by invoking `ffsclient --help` and a command-specific help with `ffsclient {command} --help`
For some collections (like `bookmarks`, `passwords`, `forms`, `history`, `tabs`) are specific subcommands available.
For example, you can list your bookmarks with `ffsclient bookmarks list`, this is preferable to the general `ffsclient list {collection}` call, because the bookmark-data in the records gets directly parsed and properly displayed.
Example
=======
Here I try to show some common usage patterns:
Get all bookmarks as json
-------------------------
```
$ ./ffsclient bookmarks list --format json --output bookmarks.json --ignore-schema-errors
$ ./ffsclient bookmarks list --format json --output bookmarks.json --ignore-schema-errors --minimized-json
```
*`--ignore-schema-errors` skips records that are in the bookmarks collection but do not contain valid data*
Get all bookmarks in netscape format (same as firefox bookmarks.html)
---------------------------------------------------------------------
```
$ ./ffsclient bookmarks list --format netscape
```
Get a single bookmark
---------------------
```
$ ./ffsclient get bookmarks "{bookmark_id}" --decoded --format json --pretty-print
```
The `--pretty-print` flag does format the json in the record payload, the surrounding json (from `--format json`) is pretty-printed by default.
If you don't want to have the envelope pretty-printed use the `--minimized-json` flag
Create a new bookmark
---------------------
```
$ ./ffsclient bookmarks create "{title}" "{url}"
$ ./ffsclient bookmarks create "{title}" "{url}" --parent "{parent-record-id}"
$ ./ffsclient bookmarks create "{title}" "{url}" --parent "{parent-record-id}" --position "{index}"
```
By default, bookmarks are created at the top-level and at the last position in the parent folder.
List all passwords
------------------
```
$ ./ffsclient passwords list --ignore-schema-errors
$ ./ffsclient passwords list --show-passwords
```
By default passwords are hidden to prevent accidental leaks.
List deleted passwords
----------------------
```
$ ./ffsclient passwords list --only-deleted
```
Also useful is the `--include-deleted` flag to show both, deleted and normal entries.
Also works with other list commands
Add a new password
------------------
```
$ ./ffsclient passwords create "{url}" "{username}" "{password}"
```
Delete a password
------------------
```
$ ./ffsclient passwords delete "{url}"
$ ./ffsclient passwords delete "{record-id}"
```
Delete any record
------------------
```
$ ./ffsclient delete "{record-id}"
$ ./ffsclient delete "{record-id}" --hard
```
*By default, the sync protocol needs tombstones. This means deleted records still exist, without their payload and wit a deleted:true flag*
*If the `--hard` flag is supplied, the record is instead completely deleted from the server*
Query the server without a session file
---------------------------------------
```
$ ./ffsclient collections --auth-login-email "{username}" --auth-login-password "{password}"
```
This does not use the normal session file an creates a completely new session for this command only.
This is genrally **not** recommended to do. Your request will look like a new client to the server, it can happen that you have to allow it via email and it is also much more inefficient.
If you don't want a session file in your home folder use `--sessionfile` to specify a more secure location
Create and read unencrypted records
-----------------------------------
```
$ ./ffsclient create "{collection}" "{id}" --raw "hello world"
$ ./ffsclient get "{collection}" "{id}" --raw --format json
$ ./ffsclient get "{collection}" "{id}" --raw --format text --data-only
```
Normally records have an encrypted payload that needs to be decrypted before it can be read (via the `--decrypted` flag in `ffsclient get`).
But you can also directly write data in the payload field.
The `--raw` flag in `ffsclient create` skips the normal encryption step and the `--raw` flag in `ffsclient get` skips the decryption.
This is only recommended for custom collections, you should never write invalid data in one of the default collections (e.g. `bookmarks`, `passwords`, etc)
Manual
======
*(copied from v1.4.0)*
*If I forgot to update the README you can always get the current version of the help with `./ffsclient --help`*
```
firefox-sync-client.
# (Use `ffsclient --help` for more detailed info)
Basic Usage:
ffsclient login Login to FF-Sync account, uses ~/.config as default session location
[--device-name=] # Send your device-name to identify the session later
[--device-type=] # Send your device-type to identify the session later
[--otp=] # A valid TOTP token, in case one is needed for the login
ffsclient refresh [--force] Refresh the current session token (via OAuth RefreshToken)
ffsclient check-session Verify that the current session is valid
ffsclient collections List all available collections
[--usage] # Include usage (storage space)
ffsclient quota Query the storage quota of the current user
ffsclient list Get a all records in a collection (use --format to define the format)
(--raw | --decoded | --ids) # Return raw data, decoded payload, or only IDs
[--after ] # Return only fields updated after this date
[--sort ] # Sort the result by (newest|index|oldest)
[--limit ] # Return max elements
[--offset ] # Skip the first elements
[--pretty-print | --pp] # Pretty-Print json in decoded data / payload (if possible)
ffsclient get Get a single record
(--raw | --decoded) # Return raw data or decoded payload
[--pretty-print | --pp] # Pretty-Print json in decoded data / payload (if possible)
[--data-only] # Only return the payload
ffsclient delete [--hard] Delete the specified record
ffsclient delete Delete all the records in a collection
ffsclient delete-all --force Delete all (!) records in the server
ffsclient create Insert a new record
(--raw | --data | --raw-stdin | --data-stdin) # The new data
ffsclient update Update an existing record
(--raw | --data | --raw-stdin | --data-stdin) # The new data
[--create] # Create a new record if the specified record-id does not exist
ffsclient meta Get storage metadata
ffsclient --help Output specific help for a single subcommand
Usage:
ffsclient bookmarks list List bookmarks (use --format to define the format)
[--ignore-schema-errors] # Skip records that cannot be decoded into a bookmark schema
[--after ] # Return only fields updated after this date
[--sort ] # Sort the result by (newest|index|oldest)
[--limit ] # Return max elements
[--offset ] # Skip the first elements
[--include-deleted] # Show deleted entries
[--only-deleted] # Show only deleted entries
[--type ] # Show only entries with the specified type
[--parent ] # Show only entries with the specified parent (by record-id), can be specified multiple times
[--linear # Do not output the folder hierachy
ffsclient bookmarks delete Delete the specified bookmark
ffsclient bookmarks create bookmark Insert a new bookmark
[--description ] # Specify the bookmark description
[--load-in-sidebar] # If specified the `LoadInSidebar` field is set to true (default is false)
[--tag ] # Add a tag to the bookmark, specify multiple times to add multiple tags
[--keyword ] # Specify the keyword (to activate the bookmark from the location bar)
[--parent ] # Specify the ID of the parent folder (if not specified the entry lives under `unfiled`)
[--position=] # The position of the entry in the parent (0 = first, default is last). Can use negative indizes.
ffsclient bookmarks create folder Insert a new bookmark-folder
[--parent ] # Specify the ID of the parent folder (if not specified the entry lives under `unfiled`)
[--position=] # The position of the entry in the parent (0 = first, default is last). Can use negative indizes.
ffsclient bookmarks create separator Insert a new bookmark-separator
[--parent ] # Specify the ID of the parent folder (if not specified the entry lives under `unfiled`)
[--position=] # The position of the entry in the parent (0 = first, default is last). Can use negative indizes.
ffsclient bookmarks update Partially update a bookmark
[--title ] # Change the bookmark title
[--url ] # Change the URL
[--description ] # Change the bookmark description
[--load-in-sidebar ] # Set the `LoadInSidebar` field
[--tag ] # Change the tags, specify multiple times to set multiple tags
[--keyword ] # Specify the keyword (to activate the bookmark from the location bar)
[--position=] # Change the position of the entry in the parent (0 = first). Can use negative indizes.
ffsclient passwords list List passwords
[--show-passwords] # Show the actual passwords
[--ignore-schema-errors] # Skip records that cannot be decoded into a password schema
[--after ] # Return only fields updated after this date
[--sort ] # Sort the result by (newest|index|oldest)
[--limit ] # Return max elements
[--offset ] # Skip the first elements
[--include-deleted] # Show deleted entries
[--only-deleted] # Show only deleted entries
ffsclient passwords delete [--hard] Delete a single password
[--is-host | --is-exact-host | --is-id] # Specify that the supplied argument is a host / record-id (otherwise both is possible)
ffsclient passwords create Insert a new password
[--form-submit-url ] # Specify the submission URL (GET/POST url set by )
[--http-realm ] # Specify the HTTP Realm (HTTP Realm for which the login is valid)
[--username-field ] # Specify the Username field (HTML field name of the username)
[--password-field ] # Specify the Password field (HTML field name of the password)
ffsclient passwords update Update an existing password
[--is-host | --is-exact-host | --is-id] # Specify that the supplied argument is a host / record-id (otherwise both is possible)
[--host ] # Update the host field
[--username ] # Update the username
[--password ] # Update the password
[--form-submit-url ] # Update the submission URL (GET/POST url set by )
[--http-realm ] # Update the HTTP Realm (HTTP Realm for which the login is valid)
[--username-field ] # Update the Username field (HTML field name of the username)
[--password-field ] # Update the Password field (HTML field name of the password)
ffsclient passwords get Insert a new password
[--is-host | --is-exact-host | --is-id] # Specify that the supplied argument is a host / record-id (otherwise both is possible)
ffsclient forms list List form autocomplete suggestions
[--name ] # Show only entries with the specified name
[--ignore-schema-errors] # Skip records that cannot be decoded into a form schema
[--after ] # Return only fields updated after this date
[--sort ] # Sort the result by (newest|index|oldest)
[--limit ] # Return max elements
[--offset ] # Skip the first elements
[--include-deleted] # Show deleted entries
[--only-deleted] # Show only deleted entries
ffsclient forms get [--ignore-case] Get all HTML-Form autocomplete suggestions for this name
ffsclient forms create Adds a new HTML-Form autocomplete suggestions
ffsclient forms delete [--hard] Delete the specified HTML-Form autocomplete suggestion
ffsclient history list List form history entries
[--ignore-schema-errors] # Skip records that cannot be decoded into a history schema
[--after ] # Return only fields after this date
[--sort ] # Sort the result by (newest|index|oldest)
[--limit ] # Return max elements
[--offset ] # Skip the first elements
[--include-deleted] # Show deleted entries
[--only-deleted] # Show only deleted entries
ffsclient history delete [--hard] Delete the specified history entry
ffsclient tabs list List synchronized tabs
[--client ] # Show only entries from the specified client (must be a valid client-id)
[--ignore-schema-errors] # Skip records that cannot be decoded into a tab schema
[--limit ] # Return max elements (clients)
[--offset ] # Skip the first elements (clients)
[--include-deleted] # Show deleted entries
[--only-deleted] # Show only deleted entries
Hint:
# If you need to supply a record-id / collection that starts with an minus, use the --!arg=... syntax
# e.g.: `ffsclient get bookmarks --!arg=-udhG86-JgpUx --decoded`
# Also if you need to supply a argument that starts with an - use the --arg=value syntax
# e.g.: `ffsclient bookmarks add Test "https://example.org" --parent toolbar --position=-3`
Common Options:
-h, --help Show this screen.
--version Show version.
-v, --verbose Output more intermediate information
-q, --quiet Do not print anything
-f , --format Specify the output format (not all subcommands support all output-formats)
# - 'text'
# - 'json'
# - 'netscape' (default firefox bookmarks format)
# - 'xml'
# - 'table'
# - 'csv'
# - 'tsv'
--table-truncate Truncate columns of table-format to fit terminal width (needs -f table)
--no-table-truncate Disable truncation of columns in table-format output
--table-columns Limit displayed columns of table-format output (comma-seperated list of headers)
--csv-filter Only print specified columns in csv/tsv output (comma-seperated index list) (needs -f csv/tsv)
--auth-server Specify the (authentication) server-url
--token-server Specify the (token) server-url
--request-retry-delay-certerr Retry delay for requests that had a certificate error (default: 5 sec)
--request-retry-delay-floodcontrol Retry delay for requests that were throttled by the server (default: 15 sec)
--request-retry-delay-servererr Retry delay for requests that failed due to server errors (default: 1 sec)
--request-retry-max Max request retries (default: 5)
--request-timeout Timeout for API request (default 10 sec)
--request-ignore-certerr Ignore certificate errors (do not verify ssl)
--color Enforce colored output
--no-color Disable colored output
--timezone Specify the output timezone
# Can be either:
# - UTC
# - Local (default)
# - IANA Time Zone, e.g. 'America/New_York'
--timeformat Specify the output timeformat (golang syntax)
-o , --output Write the output to a file
--sessionfile Specify the location of the saved session
--auth-login-email Login with the sync server without using the saved session (enforces a new, temporary session)
--auth-login-password Login with the sync server without using the saved session (enforces a new, temporary session)
--no-autosave-session Do not update the sessionfile if the session was auto-refreshed
--force-refresh-session Always auto-refresh the session, even if its not expired
--no-xml-declaration Do not print the xml declaration when using `--format xml`
--minimized-json Do not indent (pretty-print) json output when using `--format json`
Exit Codes:
0 Program exited successfully
60 Program existed with an (unspecified) error
61 Program crashed
62 Program called without arguments
63 Failed to parse commandline arguments
64 Command needs a valid session/session-file and none was found
65 The current subcommand does not support the specified output format
66 Record with this ID not found
81 (check-session): The session is not valid
82 (passwords): No matching password found
83 (create-bookmarks): Parent record is not a folder
84 (create-bookmarks): The position in the parent would be out of bounds
85 (update-bookmarks): One of the specified fields is not valid on the record type
```
Request Flowchart
=================
