Cellborg CLI

This tool provides a small, easy-to-use dashboard for managing single-cell projects on your computer. It is intended for researchers who want a simple way to organize data folders and run basic QC steps without writing code.

If this tool helps your work, please star the repository — it really helps!

Get the code — step-by-step

1. Click the green "Code" button and copy the HTTPS URL (it looks like https://github.com/NishantN2005/cellborg-cli.git).

   

2. Open the Terminal application on your computer and go to your desired location, then run these commands:

git clone https://github.com/NishantN2005/cellborg-cli.git
cd cellborg-cli

Easy setup (three steps)

Follow these three steps to prepare and run the dashboard locally. After each subsection in Step 3 there is a placeholder where you can add a screenshot.

Step 1 — Prepare Python

1. Install Python 3.10 or newer if you do not already have it. On macOS you can download the installer from python.org or use Homebrew.

   

2. Create and activate a Python virtual environment, then install packages:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Step 2 — (Optional) macOS system package

On macOS, the folder-picker dialog uses Tcl/Tk (tkinter). If the Add Project dialog does not open, you may need to install Tcl/Tk via Homebrew:

brew install tcl-tk

Step 3 — Start and use the dashboard (user steps)

3a. Start the dashboard server

python main.py

The app runs a small local web server which should open up automatically. If not try going to google and typing in localhost:8080 into the search bar.

3b. Add a project (Import)

• Click the "Add New Project" button in the dashboard.
• A folder picker will appear — choose any file within the folder that you want to upload. NOTE: The entire folder will get copied NOT just the file selected. This has to do more with the compatibility issues regarding the packages used than anything else significant.

• Give the project a title and description.

  

3c. View and manage

• After the copy completes, the project appears in the project list. Click it to view metadata and use the QC helpers.

  

QC

• Click 'Run QC', the screen will freeze for a little while some background processes run. If it is succcessful, you will be directed to the qc page.

• Once you filter your data and click 'Save', click 'Go Back to Projects'

• Notice QC changes to PA (Processing & Annotations), click on that (same deal with the pausing so only click once).

• Select your desired Leiden resolution and click 'Run Clustering'

• Click 'Next Page' and Annotate your clusters, switch between genes using the dropdown on the top-left of the graph

• Once everything looks good and you saved your annotations, click 'Next Page'

• Click 'Run Analysis' and you will get directed to the analysis dashboard

• 

• All of the analysis features are implemented and their use is very intuitive. In the future, I will put all of these instructions in wiki's so it is formatted better, but for now have fun!

Notes & troubleshooting (non-technical)

• The app copies your selected folder — it does not delete your original data. If a folder with the same name already exists in projects/, a number will be added (for example myproj-1).
• The QC and plotting features use scientific Python packages (Scanpy, AnnData and their dependencies). These are listed in requirements.txt but may need extra system libraries. You can still use the dashboard to manage and view projects without running the full QC.

Want help or improvements?

• If something doesn't work, tell me which step failed (which command and any error message) and I can help troubleshoot. The GitHub repository's "Issues" tab is a good place to report problems.

If you find this useful, please star the repo — it helps the project grow.