--- title: "Unlocking Sketch metadata: find symbols across files using sketchtool CLI, Bash, and JSON" description: Use scripts to make crawling Sketch files as easy as performing a keyword search. image: https://www.bitovi.com/hubfs/Sketchtool_1200-675.jpg --- - ![AI implementation](https://www.bitovi.com/hubfs/AIConsultingIcon.svg) [AI implementation](https://www.bitovi.com/services/ai-consulting) - ![Systems engineering](https://www.bitovi.com/hubfs/icon%20-%20backend.svg) [Systems engineering](https://www.bitovi.com/services/systems-engineering-consulting) - ![Project Management](https://www.bitovi.com/hubfs/icon%20-%20PM.svg) [Project Management](https://www.bitovi.com/services/agile-project-management-consulting) - ![Product Design](https://www.bitovi.com/hubfs/icon%20-%20design.svg) [Product Design](https://www.bitovi.com/services/product-design-consulting) - ![Frontend development](https://www.bitovi.com/hubfs/icon%20-%20frontend.svg) [Frontend development](https://www.bitovi.com/services/frontend-development-consulting) - [View more → ](https://www.bitovi.com/digital-consulting-services) We're Experts in... - [JavaScript](https://www.bitovi.com/services/frontend/javascript-consulting) - [AI training](https://www.bitovi.com/ai-training-for-software-engineers) - [Angular](https://www.bitovi.com/services/frontend/angular-consulting) - [Design systems](https://www.bitovi.com/services/axure-figma-migration) - [React](https://www.bitovi.com/services/frontend/react-consulting) - [Temporal](https://www.bitovi.com/services/backend/temporal-consulting) - [React Native](https://www.bitovi.com/services/frontend/react-consulting/react-native) - [Node.js](https://www.bitovi.com/services/backend/nodejs-consulting) Showcase ![Yum! Brands](https://www.bitovi.com/hubfs/yum-showcase-link-1.png) [View case study](https://www.bitovi.com/en/bitovi-yum-case-study) More Projects - [![Levi's](https://www.bitovi.com/hubfs/levis.svg)](https://www.bitovi.com/web-application-consulting-work/levis-ecommerce-responsive-redesign) - [![Christie's International Real Estate](https://www.bitovi.com/hubfs/christies.svg)](https://design.bitovi.com/christies) - [![BAFS](https://www.bitovi.com/hubfs/bafs.svg)](https://www.bitovi.com/ux-design-consulting/ux-case-studies/bafs-ppp) - [View more → ](https://www.bitovi.com/our-software-consulting-work) Open Source Tools We build powerful tools and open source them to support the community. [See what we've built →](https://www.bitovi.com/open-source) - [![Blog](https://www.bitovi.com/hubfs/icon%20-%20blog.svg) BlogWe post about delivering products and solving problems. ](https://www.bitovi.com/blog) - [![Partnerships](https://www.bitovi.com/hubfs/Handshake-1.svg) PartnershipsLearn about Bitovi's technology partners ](https://www.bitovi.com/partnerships) - [![Academy](https://www.bitovi.com/hubfs/icon%20-%20academy%20(4).svg) AcademyFree courses to build delivery skills ](https://www.bitovi.com/academy) - [![Open source tools](https://www.bitovi.com/hubfs/icon%20-%20open%20source.svg) Open source toolsUse or contribute to our community ](https://www.bitovi.com/open-source) Let's Connect - [![Discord](https://www.bitovi.com/hubfs/DiscordLogo.svg) Discord ](https://discord.gg/J7ejFsZnJ4) - [![LinkedIn](https://www.bitovi.com/hubfs/LinkedinLogo.svg) LinkedIn ](https://www.linkedin.com/company/bitovi/) - [![GitHub](https://www.bitovi.com/hubfs/GithubLogo.svg) GitHub ](https://github.com/bitovi/) ![Eggbot](https://www.bitovi.com/hubfs/build_assets/bitovi-limbo-cms-react/338/js_client_assets/assets/eggbot-LTGhdSGL.png) Name * Work Email * Phone What's your project? Send ### Contact Us (312) 620-0386contact@bitovi.com [ Design ](https://www.bitovi.com/blog/topic/design) | July 12, 2021 # Unlocking Sketch metadata: find symbols across files using sketchtool CLI, Bash, and JSON Use scripts to make crawling Sketch files as easy as performing a keyword search. ![The Bitovi Team](https://www.bitovi.com/hubfs/TheBitoviTeam%20(1).png) The Bitovi Team Share: [![Twitter](https://www.bitovi.com/hubfs/limbo-generated/_astro/twitter-white.os3xLc3C_Z2nW4or.svg) ](https://twitter.com/intent/tweet?text=) [![Reddit](https://www.bitovi.com/hubfs/limbo-generated/imgs/icons/reddit.png) ](http://reddit.com/submit?url=) Have you ever had the daunting task of checking whether developers coded a component (e.g., button, checkbox, alert) according to spec and needed to find ALL instances of that component in a huge collection of pages in an unfamiliar design system? Let’s say you have a spec for an alert banner (component/symbol). You know what it’s supposed to look like. But now, you need to find every single page or modal that alert appears on, how to navigate to it, and what conditions cause it to appear, so you can check that all instances are coded to spec. Gulp! You definitely *don’t* want to open file after file of page-level specs/comps, search multiple pages and artboards, in a slow tedious hunt for that elusive little component, especially if there are 100+ files and hundreds of artboards in your design system. This is the dilemma I faced on a recent project.  Here’s how my project was setup. - A Sketch symbol library held components - Components had their own specs showing padding, typography, colors, and interactions - Page-level specs showed which components were used on each page Unfortunately, there was no way to search page-level specs or give an instruction like, “Show me every page or modal where an alert banner appears.” There are plugins (e.g., [Symbol Instance Locator](https://github.com/sonburn/symbol-instance-locator), [Find all instances of symbol](https://github.com/nmwoods1/Sketch---Find-all-instances-of-symbol)) that can locate instances of symbols in an open Sketch document, but I needed to search across *all* files in the design system.  With a little ingenuity, I created this feature myself. I’m going to show you the power tool I built to fix this problem. Follow along and in the end, you’ll be able to search for symbols by keyword and see all Sketch files they appear in.* Caveats:  - If you're a designer reading this article, don't be scared off by "developer speak" or the fearful thought of using the command line (e.g., Terminal). I'm a designer, too, and want to assure you that you *can* do this. I'll walk you through it step by step. - This process works best when all symbols are part of the library (vs. documents using a mix of global library and local symbols). - *This hack relies on links between symbols in your Sketch library and instances of those symbols in your design files. If links to the library are broken, outdated, or non-existent, your keyword search won’t work. The process described below will NOT magically fix broken links to the symbol library. You will have to check these yourself. ## Unlock Sketch metadata Sketch already knows which files use which symbols, it just doesn't tell you that. We're going to make Sketch cough up that info by exporting each file's metadata. When you open a Sketch file, Sketch will check if any [library symbols are out of date](https://www.sketch.com/docs/designing/libraries/updating-library-components/). How does it know what symbols you're using and what library they come from? Your Sketch file uses metadata (e.g., filename, created date, last saved date, version, etc.). Utilizing Sketch's command-line interface (CLI), called `sketchtool`, you can view and export a Sketch file's metadata, which includes the names of all symbols used on pages and artboards to a JSON file for easy keyword search later.  ### Sketchtool [Sketchtool](https://developer.sketch.com/cli/) is built into Sketch. You don't have to install it, but you do have to configure it. For this tutorial, I will assume you are using a Mac. Feel free to make adjustments if working on a different operating system. 1. Open Terminal.  2. Type in `curl -sSL https://git.io/Jvdwg | bash -s stable` and hit Return. Using `curl` will save you the time and effort of downloading and executing the following Bash script from [https://gist.github.com/pierreneter/d45f6d981a668f543fde45d41ea54ae0](https://gist.github.com/pierreneter/d45f6d981a668f543fde45d41ea54ae0). ``` bash #!/bin/sh rm -rf /usr/local/bin/sketchtool ln -s /Applications/Sketch.app/Contents/MacOS/sketchtool /usr/local/bin/sketchtool ``` That's it. You should be all set with `sketchtool`. ### Metadata Sketchtool has 2 commands for extracting metadata. 1. `sketchtool metadata /path/to/document.sketch` 2. `sketchtool dump /path/to/document.sketch` The difference between `metadata` and `dump` is the amount of metadata you squeeze out. The latter, `dump`, is much richer. That's the command you want to use.  By default, `sketchtool` will export metadata into the terminal window, **not** into a file. You want the metadata output into a JSON file, so add `> filename.json` to the command. The `>` character means "output". For example, if your Sketch file is called "Breadcrumbs SPEC v4.sketch", you would use the following command to extract metadata into a JSON file. When filenames include spaces, you will need to use 'single' or "double" quotes around the filename. ``` sketchtool dump 'Breadcrumbs SPEC v4.sketch' > 'Breadcrumbs SPEC v4.json' ``` Ta-dah. You should now have a JSON file full of metadata in the same directory as your Sketch file.  If you only have a few Sketch files to extract metadata from, you could repeat the `sketchtool dump ..`. command for each filename. But more than likely, your design system is HUGE with dozens of files in many nested folders. Don't worry; a Bash script can help you here. ### Bash [Bash](https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29) is a command language or "the old school way to interact with computers before voice, touch, and graphical user interfaces came along." For performing bulk actions like searching, renaming, or creating files and directories, command line is the way to go.  To perform actions in bulk on multiple files, you'll want to create and run a bash (aka shell) script. To create a bash script, you'll want to open up a code editor like [Visual Studio Code](https://code.visualstudio.com/) and copy and paste one of the scripts below. You will save your script with `.sh` as the file extension, for example, `sketch-loop.sh`, in whatever file directory is most appropriate for your situation. I'll give you three options for performing JSON metadata "extractions" in bulk: 1. All Sketch files in the current directory 2. All Sketch files in the current directory and one more level deep 3. All Sketch files in the current directory and all levels deep To run a script in Terminal, navigate to the directory you saved it to using the command `cd` for "change directory" (i.e., `cd path/to/Sketch/files/and/script`). For example, if all your Sketch files were in a folder called “Design System”, you would type `cd 'Design System'` and hit Return to change directories.  Now in the correct directory, you'd type `./sketch-loop.sh` and hit Return to run the script. You will then see messages in Terminal to the effect that it's outputting/creating your JSON files.   #### Option 1: Current directory This script will find all Sketch files in the current directory, but will **not** look into folders in the same directory. JSON files will be created at the same level as their source Sketch files. Run this script if your Sketch files are all in the same folder. ``` bash #!/bin/bash for sketch_file in *.sketch; do echo "Outputting $sketch_file.json" sketchtool dump "$sketch_file" > "$sketch_file".json done ```   #### Option 2: Current directory plus one more level This script will find all Sketch files in the current directory and **will** look into folders in the same directory, but will not look into any folders inside those folders. Notice that this script is identical to the previous script except instead of `*.sketch`, we have `*/*.sketch` where `*/` means "this and the next level". JSON files will be created at the same level as their source Sketch files. Run this script if your Sketch files are in a simple directory structure that is 2 or fewer levels deep.  ``` bash #!/bin/bash for sketch_file in */*.sketch; do echo "Outputting $sketch_file.json" sketchtool dump "$sketch_file" > "$sketch_file".json done ```   #### Option 3: Current directory and all levels below This script will find all Sketch files in the current directory and **all** nested folders. It will not ignore folders with names like "_Archive" or "WIP - Work in Progress" or "DO NOT USE", so keep that in mind. If you want to ignore these folders later when you do your keyword search, you'll need to delete them from the json folder. Run this script if your Sketch files are in a more complex multi-level directory structure and you want to take care of everything at once, in bulk (vs. you running bash scripts one folder at a time). *Note*: This script assumes you have [fd](https://github.com/sharkdp/fd), which is a program to find entries in your filesystem. It is a simple, fast and user-friendly alternative to find. To check and see if you have fd installed, in Terminal, type `brew list`. This command will show all the [Homebrew](https://brew.sh/) packages you have installed (e.g., node, git, ruby, yarn). If you don't see fd on the list, type `brew install fd` and hit Return. If you don't have Homebrew installed, type `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` and hit Return to install it. Once you're all set with Homebrew and fd, create and execute the Bash script below. Unlike the above two scripts, this one will *not* create JSON files in the same directory as their source Sketch files. Instead, it will create a folder titled, "json", at the same directory level as your script and inside will be JSON files in the same directory structure as your Sketch files. Instead of having Sketch and JSON files side by side, you will have JSON files in their own "json" directory.  If you don't want JSON metadata files created for some folders, you’ll want to  use one of the two "less recursive" scripts above.  ``` bash #!/bin/bash set -x for sketch_file in $(fd .sketch); do echo "Outputting $sketch_file.json" sketchtool metadata "$sketch_file" > "$sketch_file".json done ```   ## Search for symbols Now that you've generated all those JSON metadata files, you can easily search them to find your symbols by keyword. Let's start with the JSON file you created for your symbol library. Open it in your code editor and it will look something like this. ![A JSON file showing symbol names and variations](https://www.bitovi.com/hs-fs/hubfs/symbol_names.png?width=1584&name=symbol_names.png)   In the example above, "Banners" (aka alert message banners) is a symbol; info, error, warning, and success are different permutations of that symbol. If you want to find all Sketch files that include a banner symbol, simply perform a global keyword search in your code editor for "Banners\/". ![A keyword search for banners yields results across many files](https://www.bitovi.com/hs-fs/hubfs/keyword_search.png?width=1457&name=keyword_search.png)   Right-click on the file to copy the path. ![Right-click menu showing Copy Path option selected](https://www.bitovi.com/hs-fs/hubfs/copy_path.png?width=1534&name=copy_path.png)   Open Finder. Press "Command + Shift + G" to open the “Go to the folder” dialog and paste in the path. Once in the correct folder, open your Sketch file. ![Go to the folder dialog with file path selected](https://www.bitovi.com/hs-fs/hubfs/path_selected.png?width=1600&name=path_selected.png)   Congratulations! You’ve tracked down your first symbol instance. ## Pinpoint symbol location If your Sketch file has a lot of pages and/or artboards, you can make the task of finding a symbol easier by using the [Symbol Instance Locator plugin](https://github.com/sonburn/symbol-instance-locator\)). I used [Runner](https://sketchrunner.com/) to install the plugin. ![Sketch Runner results for install symbol instance locator command](https://www.bitovi.com/hs-fs/hubfs/sketch_runner.png?width=512&name=sketch_runner.png)   Once installed, you will see the following confirmation screen. ![Symbol Instance Locator installed confirmation dialog](https://www.bitovi.com/hs-fs/hubfs/symbol_instance_locator.png?width=1594&name=symbol_instance_locator.png)   To use Symbol Instance Locator, find at least one instance of the component you want to search for, select it, then press "Command + Option + Shift + L" to find all other instances. The dialog that appears will show you which artboards components are on and allow you to click on them to jump right to them. ![Symbol Instance Locator results for Banner symbol](https://www.bitovi.com/hs-fs/hubfs/symbol_instance_locator_2.png?width=346&name=symbol_instance_locator_2.png)   See? Easy-peasy. You deserve an "I hacked Sketch today" sticker. :-) Want to do more incredible things together? [Contact Us](https://docs.google.com/document/u/0/d/1h6UNOXQ2Qn-Ucj96K9WuCeP8i9qoQDv-/edit) to discuss your project.   [![Tag for user experience](https://www.bitovi.com/hubfs/limbo/icons/tag.svg) user experience ](https://www.bitovi.com/blog/topic/user-experience) Previous Post ![](https://www.bitovi.com/hs-fs/hubfs/rxjs7.png?height=117&name=rxjs7.png) [ What’s New in RxJS 7: Small Bundles and Big Changes to share() ](https://www.bitovi.com/blog/whats-new-in-rxjs-7-small-bundles-and-big-changes-to-share)   Next Post ![React Image](https://www.bitovi.com/hs-fs/hubfs/Screen%20Shot%202021-07-27%20at%208.57.44%20PM.png?height=117&name=Screen%20Shot%202021-07-27%20at%208.57.44%20PM.png) [ A Simple Asynchronous Alternative to React's useReducer ](https://www.bitovi.com/blog/simple-async-alternative-to-use-reducer) ```json { "@context" : "http://schema.org", "@type" : "Organization", "address" : { "@type" : "PostalAddress", "addressCountry" : "United States", "addressLocality" : "Libertyville", "addressRegion" : "IL", "postalCode" : "60048", "streetAddress" : "1134 Pine Tree Lane " }, "alternateName" : "Bitovi", "areaServed" : { "@type" : "GeoCircle", "geoMidpoint" : { "@type" : "GeoCoordinates", "latitude" : "41.8781", "longitude" : "87.6298" }, "geoRadius" : "5000 km" }, "description" : "Bitovi is a UX, UI design and front-end JavaScript development consulting company", "email" : "contact@bitovi.com", "image" : "https://www.bitovi.com/hubfs/bitovi-logo-x2.png", "logo" : "https://www.bitovi.com/hubfs/bitovi-logo-23-1.svg", "mainEntityOfPage" : { "@id" : "https://www.bitovi.com/blog/unlocking-sketch-metadata-find-symbols-across-files-using-sketchtool-cli-bash-and-json", "@type" : "WebPage", "description" : "Use scripts to make crawling Sketch files as easy as performing a keyword search." }, "naics" : "541511", "name" : "Bitovi Web App Consulting", "sameAs" : [ "https://www.facebook.com/BitoviLLC/", "https://twitter.com/bitovi", "https://www.linkedin.com/company/bitovi" ], "telephone" : "312-620-0386", "url" : "http://bitovi.com" } ``` ```json { "@context" : "http://schema.org", "@type" : "BlogPosting", "author" : { "@type" : "Person", "name" : "The Bitovi Team" }, "dateModified" : "July 12, 2021, 3:10:16 PM", "datePublished" : "2021-07-12 15:10:15", "description" : "Use scripts to make crawling Sketch files as easy as performing a keyword search.", "headline" : "Unlocking Sketch metadata: find symbols across files using sketchtool CLI, Bash, and JSON", "image" : { "@type" : "ImageObject", "url" : "https://www.bitovi.com/hubfs/Sketchtool_1200-675.jpg" }, "publisher" : { "@type" : "Organization", "logo" : { "@type" : "ImageObject", "url" : "https://www.bitovi.com/hubfs/bitovi-logo-23-1.svg" }, "name" : "Bitovi" } } ```