Skip to content

installation.mdx

Latest commit

 

History

History
170 lines (127 loc) · 5.94 KB

installation.mdx

File metadata and controls

170 lines (127 loc) · 5.94 KB
title How to Install photo-cli on macOS, Windows, and Linux
description Step-by-step instructions to install photo-cli as a self-contained executable, via Homebrew, as a .NET global tool, or in a container (Docker, Podman), including PATH troubleshooting.
sidebarTitle Installation

photo-cli runs on macOS, Windows, and Linux across arm64, x64, and x86 architectures. You can install it as a self-contained executable, through Homebrew on macOS and Linux, as a .NET global tool on any platform, or in a container (Docker, Podman). Choose the method that fits your operating system below.

Prerequisites

photo-cli requires the .NET SDK 10 or later when installing as a .NET tool. The dotnet command must be available on your PATH before you install photo-cli as a .NET tool.

You can install the .NET SDK in two ways:

brew install dotnet-sdk --cask
If you install photo-cli via Homebrew on macOS, the .NET SDK is bundled automatically and you do not need to install it separately.

Installation

The easiest way to run photo-cli without installing any dependency. The executable contains the .NET runtime in a single file and is available for macOS, Windows, and Linux across arm64, x64, and x86 architectures. 
Download the executable for your OS and architecture directly from the [releases page](https://github.com/photo-cli/photo-cli/releases).
Homebrew is the recommended installation method on macOS and Linux. It handles all dependencies, including the .NET runtime, and keeps photo-cli up to date automatically. 
<Steps>
  <Step title="Add the photo-cli Homebrew tap">
    Register the photo-cli tap so Homebrew can find the package:

    ```bash
    brew tap photo-cli/homebrew-photo-cli
    ```

    The tap is hosted at [https://github.com/photo-cli/homebrew-photo-cli](https://github.com/photo-cli/homebrew-photo-cli).
  </Step>
  <Step title="Install photo-cli">
    Install the package from the tap:

    ```bash
    brew install photo-cli
    ```

    You can also run both commands in a single line:

    ```bash
    brew tap photo-cli/homebrew-photo-cli && brew install photo-cli
    ```
  </Step>
  <Step title="Verify the installation">
    Confirm that photo-cli is available in your terminal:

    ```bash
    photo-cli --version
    ```
  </Step>
</Steps>
You can install photo-cli as a .NET global tool on any platform where the .NET SDK is available. 
<Steps>
  <Step title="Install the .NET SDK">
    Download and install the .NET SDK 10 or later from [https://dotnet.microsoft.com/en-us/download](https://dotnet.microsoft.com/en-us/download). Confirm the installation:

    ```bash
    dotnet --version
    ```
  </Step>
  <Step title="Install photo-cli globally">
    Install the tool from NuGet:

    ```bash
    dotnet tool install photo-cli -g
    ```

    The package is available at [https://www.nuget.org/packages/photo-cli/](https://www.nuget.org/packages/photo-cli/).
  </Step>
  <Step title="Verify the installation">
    ```bash
    photo-cli --version
    ```
  </Step>
</Steps>
Using the published Docker [image on DockerHub](https://hub.docker.com/r/photocli/photocli), you can run photo-cli in an isolated container environment by mounting your photographs and output directory as bind mounts. 
```bash
docker run --rm \
  --volume ./test-photographs:/photos/input \
  --volume ./archive:/photos/output \
  photocli/photocli archive \
    --input /photos/input \
    --output /photos/output \
    --album-type DateRange \
    --album-name My-Album \
    --auto-reverse-geocode-album \
    --expected-day-range 7300 \
    --delete-on-source \
    --reverse-geocode OpenStreetMapFoundation \
    --openstreetmap-properties country city
```

<Note>
  The bind-mounted directories appear as empty directories in the container filesystem and must be given as the input and output directories to the application. The container can be safely discarded after execution.
</Note>

Accessing the application

After installing photo-cli globally, the photo-cli command is available in any terminal session:

photo-cli [command]
photo-cli help [command]

Troubleshooting

Command not found

If your terminal reports photo-cli: command not found after installation, the .dotnet/tools directory is not on your PATH. Add it manually using the steps below for your shell.

macOS (zsh)

Add the following line to your ~/.zshenv file:

export PATH="$PATH:/Users/[your-account-name]/.dotnet/tools"

Linux (bash)

Add the following line to your ~/.profile file:

export PATH="$PATH:/home/[your-account-name]/.dotnet/tools"

Replace [your-account-name] with your actual system username, then open a new terminal session for the change to take effect.

The exact path to `.dotnet/tools` may differ depending on how you installed the .NET SDK. Check your installation directory if the paths above do not work.

Uninstallation

.NET Tool

dotnet tool uninstall -g photo-cli

MCP Server Setup

The mcp command is built into photo-cli and requires no additional installation. It starts an MCP stdio server on top of an existing archive folder (one previously created with photo-cli archive).

See the MCP command page for setup instructions for Claude Code, Claude Desktop, VS Code, and MCP Inspector.