1
0
www.mikescher.com/www/statics/programs/ffsclient_description.md

24 KiB

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 or custom data.

Table of contents

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/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:

Usage

Before the first use you have to authenticate your client and create a session.
Call ffsclient {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 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. 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) 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 teh default collections (e.g. bookmarks, passwords, etc)

Manual

(copied from v1.2.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 <command> --help` for more detailed info)

Basic Usage:
  ffsclient login <login> <password>                               Login to FF-Sync account, uses ~/.config as default session location
            [--device-name=<name>]                                 
            [--device-type=<type>]                                 
  ffsclient refresh [--force]                                      Refresh the current session token (BID Assertion)
  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 <collection>                                      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 <rfc3339>]                                      # Return only fields updated after this date
            [--sort <sort>]                                          # Sort the result by (newest|index|oldest)
            [--limit <n>]                                            # Return max <n> elements
            [--offset <o>]                                           # Skip the first <n> elements
            [--pretty-print | --pp]                                  # Pretty-Print json in decoded data / payload (if possible)
  ffsclient get <collection> <record-id>                           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 <collection> <record-id> [--hard]               Delete the specified record
  ffsclient delete <collection>                                    Delete all the records in a collection
  ffsclient delete-all --force                                     Delete all (!) records in the server
  ffsclient create <collection> <record-id>                        Insert a new record
            (--raw <r> | --data <d> | --raw-stdin | --data-stdin)    # The new data
  ffsclient update <collection> <record-id>                        Update an existing record
            (--raw <r> | --data <d> | --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 <sub> --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 <rfc3339>]                                      # Return only fields updated after this date
            [--sort <sort>]                                          # Sort the result by (newest|index|oldest)
            [--limit <n>]                                            # Return max <n> elements
            [--offset <o>]                                           # Skip the first <n> elements
            [--include-deleted]                                      # Show deleted entries
            [--only-deleted]                                         # Show only deleted entries
            [--type <folder|separator|bookmark|...>]                 # Show only entries with the specified type
            [--parent <id>]                                          # 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 <id>                                  Delete the specified bookmark
  ffsclient bookmarks create bookmark <title> <url>                Insert a new bookmark
            [--description <desc>]                                   # Specify the bookmark description
            [--load-in-sidebar]                                      # If specified the `LoadInSidebar` field is set to true (default is false)
            [--tag <tag>]                                            # Add a tag to the bookmark, specify multiple times to add multiple tags
            [--keyword <kw>]                                         # Specify the keyword (to activate the bookmark from the location bar)
            [--parent <id>]                                          # Specify the ID of the parent folder (if not specified the entry lives under `unfiled`)
            [--position=<idx>]                                       # The position of the entry in the parent (0 = first, default is last). Can use negative indizes.
  ffsclient bookmarks create folder <title>                        Insert a new bookmark-folder
            [--parent <id>]                                          # Specify the ID of the parent folder (if not specified the entry lives under `unfiled`)
            [--position=<idx>]                                       # 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 <id>]                                          # Specify the ID of the parent folder (if not specified the entry lives under `unfiled`)
            [--position=<idx>]                                       # The position of the entry in the parent (0 = first, default is last). Can use negative indizes.
  ffsclient bookmarks update <id>                                  Partially update a bookmark
            [--title <title>]                                        # Change the bookmark title
            [--url <url>]                                            # Change the URL
            [--description <desc>]                                   # Change the bookmark description
            [--load-in-sidebar <true|false>]                         # Set the `LoadInSidebar` field
            [--tag <tag>]                                            # Change the tags, specify multiple times to set multiple tags
            [--keyword <kw>]                                         # Specify the keyword (to activate the bookmark from the location bar)
            [--position=<idx>]                                       # 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 <rfc3339>]                                      # Return only fields updated after this date
            [--sort <sort>]                                          # Sort the result by (newest|index|oldest)
            [--limit <n>]                                            # Return max <n> elements
            [--offset <o>]                                           # Skip the first <n> elements
            [--include-deleted]                                      # Show deleted entries
            [--only-deleted]                                         # Show only deleted entries
  ffsclient passwords delete <host|id> [--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 <host> <username> <password>          Insert a new password
            [--form-submit-url <url>]                                # Specify the submission URL (GET/POST url set by <form>)
            [--http-realm <realm>]                                   # Specify the HTTP Realm (HTTP Realm for which the login is valid)
            [--username-field <name>]                                # Specify the Username field (HTML field name of the username)
            [--password-field <name>]                                # Specify the Password field (HTML field name of the password)
  ffsclient passwords update <host|id>                             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 <url>]                                           # Update the host field
            [--username <user>]                                      # Update the username
            [--password <pass>]                                      # Update the password
            [--form-submit-url <url>]                                # Update the submission URL (GET/POST url set by <form>)
            [--http-realm <realm>]                                   # Update the HTTP Realm (HTTP Realm for which the login is valid)
            [--username-field <name>]                                # Update the Username field (HTML field name of the username)
            [--password-field <name>]                                # Update the Password field (HTML field name of the password)
  ffsclient passwords get <host|id>                                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 <n>]                                             # Show only entries with the specified name
            [--ignore-schema-errors]                                 # Skip records that cannot be decoded into a form schema
            [--after <rfc3339>]                                      # Return only fields updated after this date
            [--sort <sort>]                                          # Sort the result by (newest|index|oldest)
            [--limit <n>]                                            # Return max <n> elements
            [--offset <o>]                                           # Skip the first <n> elements
            [--include-deleted]                                      # Show deleted entries
            [--only-deleted]                                         # Show only deleted entries
  ffsclient forms get <name> [--ignore-case]                       Get all HTML-Form autocomplete suggestions for this name
  ffsclient forms create <name> <value>                            Adds a new HTML-Form autocomplete suggestions
  ffsclient forms delete <id> [--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 <rfc3339>]                                      # Return only fields after this date
            [--sort <sort>]                                          # Sort the result by (newest|index|oldest)
            [--limit <n>]                                            # Return max <n> elements
            [--offset <o>]                                           # Skip the first <n> elements
            [--include-deleted]                                      # Show deleted entries
            [--only-deleted]                                         # Show only deleted entries
  ffsclient history delete <id> [--hard]                           Delete the specified history entry

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 <fmt>, --format <fmt>                                         Specify the output format (not all subcommands support all output-formats)
                                                                     # - 'text'
                                                                     # - 'json'
                                                                     # - 'netscape'   (default firefox bookmarks format)
                                                                     # - 'xml'
                                                                     # - 'table'
  --auth-server <url>                                              Specify the (authentication) server-url
  --token-server <url>                                             Specify the (token) server-url
  --request-retry-delay-certerr <sec>                              Retry delay for requests that had a certificate error (default: 5 sec)
  --request-retry-delay-floodcontrol <sec>                         Retry delay for requests that were throttled by the server (default: 15 sec)
  --request-retry-delay-servererr <sec>                            Retry delay for requests that failed due to server errors (default: 1 sec)
  --request-retry-max <num>                                        Max request retries (default: 5)
  --request-timeout <sec>                                          Timeout for API request (default 10 sec)
  --color                                                          Enforce colored output
  --no-color                                                       Disable colored output
  --timezone <tz>                                                  Specify the output timezone
                                                                     # Can be either:
                                                                     #   - UTC
                                                                     #   - Local (default)
                                                                     #   - IANA Time Zone, e.g. 'America/New_York'
  --timeformat <url>                                               Specify the output timeformat (golang syntax)
  -o <f>, --output <f>                                             Write the output to a file
  --sessionfile <cfg>                                              Specify the location of the saved session
  --auth-login-email <email>                                       Login with the sync server without using the saved session (enforces a new, temporary session)
  --auth-login-password <pw>                                       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

FFSync-Flowchart