ksdiff is a command line tool used to launch Kaleidoscope from the Terminal and other apps. It offers a solution for two common scenarios, comparing input and merging input into and output.

Comparing Files

The following simplest possible command will open file1 and file2 in a new comparison in Kaleidoscope.

ksdiff file1 file2

Merging and Conflicts

ksdiff also allows you to start a merge operation, helping you to resolve potential conflicts between the two inputs. Here's a simple sample call opening file1 and file2, allowing you to merge both into a result outfile. Note that outfile does not need to exist when you call ksdiff, it will be created if needed.

ksdiff --merge --output outputfile file1 file2

Advanced Usage

Enjoy the real power of ksdiff by combining ksdiff with other tools and constructs of your shell:

ksdiff <(pngquant 4 image.png -o -) <(pngquant 256 image.png -o -) image.png

The example above compares a PNG image with two compressed variants of itself using indexed colors. See below in Further Reading to find a blog post going into such use cases.

Help Page

This is what typing ksdiff --help shows on the command line.

usage: ksdiff - send files to Kaleidoscope
  --version                             show version information and exit
  -h, --help                            show this help message and exit

  [-w, --wait | -W, --no-wait]          whether to wait for the document to be
                                        closed in Kaleidoscope before exiting
                                        the implied default varies per command
  [-l, --label LABEL]                   use LABEL as the visible label for the
                                        tab in Kaleidoscope, instead of the
                                        default value, which is inferred from
                                        the arguments passed to ksdiff’s parent
  --no-stdin                            never read stdin even if we receive an
                                        open pipe - needed for some host apps
                                        e.g. JetBrains products
  [-s, --snapshot | -S, --no-snapshot]  whether the file is temporary. this
                                        option will override the heuristics
                                        ksdiff would otherwise use to determine
                                        this state.

 [--diff]              send files to open  ----------------------------( diff )--
                                        default if no other command given
                                        implies --no-wait

    FILE [opt] [...]                    the files to diff, '-' represents stdin
                                        stdin will be prepended to the file list
                                        if no '-' is provided.

 --partial-changeset   send part of a changeset  ---------( partial-changeset )--
                                        implies --no-wait

    [--UUID UUID]                       use UUID to select which document to
                                        add this changeset item to; follow this
                                        with --mark-changeset-as-closed UUID
                                        to tell Kaleidoscope that no more
                                        changes are expected. if unspecified,
                                        Kaleidoscope will watch the process
                                        calling ksdiff and close the changeset
                                        when it exits.
    [--relative-path PATH]              use PATH to describe the filename and
                                        location for this changeset item within
                                        its root (e.g. a source repository)
    FILE [opts] FILE [opts]             the files to diff

 --mark-changeset-as-closed UUID        marks the partial changeset submitted
                                        under the given UUID as being closed

 --changeset           send a complete changeset   ---------------( changeset )--
                                        implies --no-wait
    --filelist                          begin a file list (changeset item)
      [--relative-path PATH]            use PATH to describe the filename and
                                        location for this changeset item within
                                        its root (e.g. a source repository)
      FILE [opts] FILE [opts]           the files to diff

 --merge               send a merge   -------------------------------( merge )--
                                        implies --wait
    --output OUTPUT                     use OUTPUT as the destination path for
                                        this merge. creates OUTPUT if it does
                                        not exist.
    [--base BASE]                       use BASE as the base content for this
                                        merge. can improve the quality of the
                                        default selections for some merges.
    FILE [opts] FILE [opts]             the files to merge

Further Reading

We recently posted a series of articles on our blog describing both basics and tips & tricks for ksdiff. After reading those articles you should be able to make the most of ksdiff for your workflow. We also posted a very brief tutorial on how to use the command line on macOS.

Resolving Issues

If you have any issues with ksdiff and its operation, please update Kaleidoscope to version 3.6 or later. If you haven't done so, Kaleidoscope 3.6 will once need to update the ksdiff installation. The procedure is different for the Direct and the App Store version of Kaleidoscope:

  • Direct: Follow the instructions presented in Kaleidoscope. You'll need to enter user and password of an administrator of your computer (typically yourself), so Kaleidoscope can remove the old ksdiff tool and install the new link.
  • App Store: The App Store version of Kaleidoscope is running in App Sandbox, as required by Apple for the App Store. This basically means it has a very limited set of permissions to do things on your system. Kaleidoscope has no permission to remove the previous installation of the ksdiff tool, which is located in /usr/local/bin. Kaleidoscope 3.6 or later will show you an external Uninstaller that will carry out that task for your (after you entering your password). Once the old version has been removed, Kaleidoscope can request permission (again, through you entering your password) to install the new link for ksdiff.


Can’t find an answer to your question here? Send us an email and we’ll help you.