Home ▶Command Line Tool

# Command Line Tool

Kaleidoscope comes with a command-line tool, called `ksdiff`, which you can use to open files from the command-line or from a script.

### Installation

Before you can use `ksdiff`, you need to install it from the Integration window. To install `ksdiff`:

1. Choose Kaleidoscope > Integration... from the main menu
2. Go to the "Command Line Tool" section
3. Follow the instructions

### Starting a Comparison with ksdiff

Examples:

- `ksdiff file1 file2 file3`
- `ksdiff ~/Desktop/*.jpg`
- `ksdiff folderA/ folderB/`

If you give `ksdiff` a set of paths as arguments, it will launch Kaleidoscope if it isn't open yet, and then create a new tab with those documents. If you supply more than 2 files as arguments, Kaleidoscope will open the File Shelf and display all the files.

### Waiting Before Exiting

`ksdiff -w file1 file2`\

If you use ksdiff in a script, it might be preferable to have ksdiff open until the comparison it started closes. This way you can remove temporary files you created after the comparison is done, or do some other action after you're sure the user has seen the comparison. This can be done with the `-w` or `--wait` command line switch.

To learn more about the ksdiff command line tool, run `ksdiff --help` to get an overview of its options:

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

      --supports-capability CAPABILITY      prints YES if CAPABILITY is supported,
                                            otherwise prints NO. the capabilities
                                            this version of ksdiff supports are:
                                            partial-changesets-v1
                                            changesets-v1
                                            diffs-v1
                                            merges-v1

    command options:
      [--wait, -w | --no-wait]              whether to wait for the document to be
                                            closed in Kaleidoscope before exiting
      [--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
                                            process

    FILE options:
      [--snapshot | --no-snapshot]          whether the file is temporary. this
                                            option will override the heuristics
                                            ksdiff would otherwise use to determine
                                            this state.

    commands:
      --partial-changeset                   send part of a 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 FILE                           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
                                            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 FILE                         the files to diff

      --merge                               send a 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 FILE                           the files to merge

      [--diff]                              send a diff
                                            implies --no-wait
        FILE [...]                          the files to diff