Getting Started¶

System Requirements¶

Requirement	Details
Operating system	Linux (X11 or Wayland) or macOS
JDK	21 (provided automatically by the Nix dev shell or bundled in native packages)
Disk space	~200 MB for the application; database grows with your data
Salesforce CLI	Optional. Required only for Salesforce sync features
AI CLI binary	Optional. Required only for meeting summaries and AI-generated content

Installation¶

NixOS (flake input)¶

Add Upsight as a flake input in your system configuration:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    upsight.url = "github:bashfulrobot/upsight"; # latest main
    # Or pin to a release:
    # upsight.url = "github:bashfulrobot/upsight/v0.1.0";
  };

  outputs = { nixpkgs, upsight, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ({ pkgs, ... }: {
          environment.systemPackages = [
            upsight.packages.${pkgs.system}.default
          ];
        })
      ];
    };
  };
}

Or use the overlay to add pkgs.upsight:

# flake.nix
{
  inputs.upsight.url = "github:bashfulrobot/upsight";

  outputs = { nixpkgs, upsight, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        { nixpkgs.overlays = [ upsight.overlays.default ]; }
        ({ pkgs, ... }: {
          environment.systemPackages = [ pkgs.upsight ];
        })
      ];
    };
  };
}

nix-darwin (macOS with Nix)¶

Same pattern as NixOS — add the flake input and include the package:

# flake.nix
{
  inputs = {
    darwin.url = "github:LnL7/nix-darwin";
    upsight.url = "github:bashfulrobot/upsight";
  };

  outputs = { darwin, upsight, ... }: {
    darwinConfigurations.myhost = darwin.lib.darwinSystem {
      system = "aarch64-darwin";
      modules = [
        ({ pkgs, ... }: {
          environment.systemPackages = [
            upsight.packages.${pkgs.system}.default
          ];
        })
      ];
    };
  };
}

home-manager (any system with Nix)¶

# In your home-manager config
{ pkgs, inputs, ... }: {
  home.packages = [
    inputs.upsight.packages.${pkgs.system}.default
  ];
}

Nix (ad hoc, no flake config)¶

Run without installing:

nix run github:bashfulrobot/upsight

Build and install to the Nix store:

nix build github:bashfulrobot/upsight
./result/bin/upsight

Pin to a release:

nix run github:bashfulrobot/upsight/v0.1.0

.deb package (Debian, Ubuntu)¶

Build the .deb from source:

nix develop --command just package-deb

The package is written to build/compose/binaries/main/deb/. Install it with:

sudo dpkg -i build/compose/binaries/main/deb/upsight_0.1.0-1_amd64.deb

AppImage (any Linux)¶

nix develop --command just package

Find the AppImage in build/compose/binaries/main/app-image/. Make it executable and run:

chmod +x Upsight-*.AppImage
./Upsight-*.AppImage

.dmg (macOS)¶

nix develop --command just package-dmg

Open the .dmg from build/compose/binaries/main/dmg/ and drag Upsight to your Applications folder.

From source (development)¶

git clone https://github.com/bashfulrobot/upsight.git
cd upsight
nix develop --command just run

Pinning to a Release¶

Nix flake inputs are pinned by commit hash in flake.lock. To update to the latest:

nix flake update upsight

To pin to a specific release tag (e.g., v0.1.0):

inputs.upsight.url = "github:bashfulrobot/upsight/v0.1.0";

Release tags match the version in the application. Each tagged release is a tested, stable snapshot.

First Launch¶

When you start Upsight for the first time:

The application creates its configuration and data directories (see Settings > Paths for locations)
An empty SQLite database is initialized at the default data path
You land on the Dashboard, which will be empty until you add accounts

Connecting to Salesforce¶

Salesforce integration requires the Salesforce CLI (sf) to be installed and authenticated.

Install the Salesforce CLI if you have not already:
```
npm install -g @salesforce/cli
```
Authenticate with your org:
```
sf org login web
```
This opens a browser window where you log in to Salesforce. The CLI stores credentials locally.
In Upsight, go to Settings > Salesforce CLI. The app auto-detects the sf binary on your PATH. If it is installed in a non-standard location, select it from the dropdown or enter a custom path.
Once authenticated, click the Sync button in the sidebar to pull your accounts from Salesforce.

Tip

You can also import individual accounts by clicking New Account on the Accounts screen and searching Salesforce directly.

Setting Up an AI Assistant¶

Meeting summaries and the monthly update wizard's AI features require a CLI-based AI tool.

Supported binaries (auto-detected from PATH):

claude (Anthropic Claude CLI)
gemini (Google Gemini CLI)
Other CLI tools that accept a prompt on stdin

To configure:

Go to Settings > AI Assistant
The app shows which binary it detected. Select a different one from the dropdown, or enter a custom path.
Enter your name in the Your Name field -- this is used in first-person AI-generated content like CXM sentiment updates.

Note

The AI binary must be independently authenticated. Upsight invokes it as a subprocess and does not manage API keys or tokens.