framer-cli

Framer CLI

The Framer CLI allows for the building and publishing your Framer folder projects via the command line.

🗃 Table of Contents

• Installation
  • Dependency Free
  • Global
  • Local
• Commands
  • authenticate
  • build
  • publish
    • Options
    • Versioning
    • Metadata
  • help
• Integration
  • Continuous Integration
  • Github Actions

👩‍💻 Installation

✨ Dependency Free

In nearly all cases, it is advisable to use npx (which shipped with npm@5.2.0) to execute framer-cli commands, preventing the need to add the package as a dependency:

npx framer-cli help

🌍 Global

If publishing packages from a local machine and npx is not a viable option, it is best to globally install the framer-cli package:

yarn global add framer-cli
# or
npm install -g framer-cli

The global installation will make the framer command directly available via the command line:

framer help

🖥 Local

In very rare cases, it might be necessary to install the framer-cli as a devDependency of a JavaScript project. The framer-cli package can be installed like any other dependency:

yarn add -D framer-cli
# or
npm install --save-dev framer-cli

This will make a framer command available to be run by inside the directory with either yarn, npx, or by directly calling the bin file:

yarn framer
# or
npx framer
# or
./node_modules/.bin/framer

🕹 Commands

The Framer CLI exposes four commands:

• 🔑 authenticate
• 📦 build
• 🚢 publish
• 📖 help

🔑 authenticate

npx framer-cli authenticate <email@address>

In order to publish a package, the CLI must be able to verify the identity of the user using a special token. This is done through an authentication flow where by an email is sent to the registered user with a link, which when clicked, creates a special FRAMER_TOKEN that is printed in the terminal. This token is used as an environment variable for publishing packages to both public or private stores under the authenticated user's name.

📦 build

npx framer-cli build [path/to/project.framerfx]

The build command ensures that the project is in a valid state for publishing.

If the command is being run inside the Framer project, there is no need to specify the path to the project. However, if the command is being run from outside the project, the project path must be provided as a second argument.

🚀 publish

env FRAMER_TOKEN=<token> npx framer-cli publish [path/to/project.framerfx] [--yes] [--major] [--public] [--new=<name>]

The publish command is responsible for:

1. Building the project
2. Managing project versioning (defaults to minor version)
3. Publishing the project to the store

The publish command requires a FRAMER_TOKEN environment variable for publishing. This token is unique to a given individual and is used for both authentication and determining the user's available private store, if any.

If a path to a project is provided, that path is resolved relative to the directory where the script is called from.

📑 Options

The publish command also exposes a series of command line options:

Option	Description	Default
yes	Automatically confirm all prompts. This is especially useful when publishing from a CI.	false
major	Override the default versioning strategy (minor bump) to instead use a major version bump.	false
public	Publish the package to the public Framer store. This flag must be set if the user does not have access to a private store.	false
new	Provide a name for the package when being published for the first time. If the package has previously been published, this argument cannot be set.	undefined

Available options can also be seen in the terminal by running:

npx framer-cli help

🗂 Versioning

By default, framer-cli will look at the Framer repository to find the last published version and then publish the Framer package with the next version, either a minor or major bump depending on the CLI arguments.

However, it is possible to override this behavior by manually updating package.json version property. If the new version is higher than the last published version, it will be used without any change.

🖇 Metadata

Artwork for Framer packages is supported through specially named images in the metadata directory:

• icon.png at 100x100
• artwork.png at 1600x1200

Similarly, descriptions for Framer packages come from their README.md file, with full Markdown syntax support.

📖 help

The help command provides a general overview of each of the commands, their purpose, and their options. It is also possible to get help by running any of the above commands with the -h or --help flag.

🔮 Integration

🚚 Continuous Integration

One of the key aspects of framer-cli is the enablement of automated Framer package publishing. By combining the script with a CI workflow, it becomes possible to always keep the Framer package in the store in sync with the Framer package in the repository.

As an example of integrating framer-cli with an external CI service, here is a small CircleCI configuration that publishes a Framer package every time a commit is made to the master branch.

Note that this example assumes that the FRAMER_TOKEN environment variable has already been set in the CI project settings.

# Javascript Node CircleCI 2.0 configuration file
#
# Check https://circleci.com/docs/2.0/language-javascript/ for more details
#
version: 2
jobs:
  publish:
    docker:
      - image: circleci/node:10

    working_directory: ~/repo

    steps:
      - checkout
      - run: yarn
      - run: npx framer-cli publish

workflows:
  version: 2
  publish:
    jobs:
      - publish:
          filters:
            branches:
              only: master

🤖 Github Actions

It is also possible to use Github Actions to automate the release of a Framer package without the use of a separate CI. An example of a build and publish workflow, ready to be cloned, can be found here.