Kitsu Project Sync (FolderSync)

Automatically creates and maintains local VFX project folders from your Kitsu studio server.

When someone adds a project, sequence, shot, or asset in Kitsu, this app creates the matching folders on your machine.

Default project root: projectRoot/ at the root of this repository (created automatically).

You can confirm or change this during first-time setup.

---

Easy start — from zero to production ready

This section is for people who are not computer experts. Follow the steps in order. You only need to do the setup once.

What you need before starting

Ask your supervisor / IT if you do not know these:

1. A Windows or Linux computer on the studio network
2. Access to the Kitsu server (ask IT for the URL; placeholder example: http://kitsu.local:8012)
3. Your Kitsu email and password
4. Write access to a local project folder (default: projectRoot/ in this repository)
5. This project folder on your machine (the folder that contains FolderSync)

---

Step 1 — Install Python (one time)

Windows

1. Open a browser and go to: https://www.python.org/downloads/
2. Download Python 3.12 (or newer 3.12+).
3. Run the installer.
4. Important: check the box “Add python.exe to PATH”.
5. Click Install Now.

Check it:

1. Press Windows, type cmd, press Enter.
2. Run: python --version

Linux

On Ubuntu / Debian:

sudo apt update
sudo apt install -y python3 python3-venv python3-pip
python3 --version

Also install tray / keyring support if needed:

sudo apt install -y libxcb-cursor0 libsecret-1-0

---

Step 2 — Open the project folder in a terminal

Windows

1. Open File Explorer.
2. Go to the folder that contains FolderSync.
3. Click the address bar, type cmd, press Enter.

Linux

cd /path/to/kitsuProjectSync

---

Step 3 — Create the virtual environment (one time)

Windows

python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -r FolderSync\requirements.txt

Linux

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

Wait until downloads finish. If you see “Successfully installed…”, you are good.

Tip: Every time you open a new terminal later, activate the venv again:

• Windows: .venv\Scripts\activate
• Linux: source .venv/bin/activate

You should see (.venv) at the start of the line.

---

Step 4 — First-time setup (project root + login)

Still in the terminal (with (.venv) active), run:

python FolderSync/main.py

(On Windows, python FolderSync\main.py also works.)

What happens the first time

1. A welcome screen asks for your Project root folder.
2. Accept the default for your OS, or type the path IT gave you.
3. Confirm the Kitsu server URL (default is usually fine).
4. Enter your Kitsu email.
5. Enter your password (it will not show on screen — that is normal).
6. Choose Yes to remember login (stores the password in the OS credential store — not in a plain text file).

When you see First-time setup complete, press Enter. You land on the main menu:

---

Step 5 — Test that Kitsu works

In the colorful menu:

1. Type 4 and press Enter (Test connection).
2. You should see Connected successfully and a list of projects.
3. Press Enter to go back to the menu.

If it fails:

• Check you are on the studio network / VPN
• Re-check email/password with option 2 Setup config
• Ask IT if the Kitsu server address changed

---

Step 6 — Run a first sync (safe test)

1. From the menu, type 5 and press Enter (Run sync once).
2. Wait until it says sync completed.
3. Type 7 and press Enter to open your project root in the file manager.
4. Confirm project / shot / asset folders appeared under your project root.

To stop a sync while it is running: press Ctrl+X in the terminal.

---

Step 7 — Go production ready (daily use)

From the menu, type 1 and press Enter (Launch app).

That starts:

• A small dashboard window
• A system tray icon
• Automatic background sync (checks Kitsu every 30 seconds by default)

How artists should use it day to day

1. Start the app in the morning (activate venv, run python FolderSync/main.py, then option 1).
2. Leave it running in the tray.
3. Work in your folders under the configured project root.
4. New Kitsu shots/assets appear as folders automatically.
5. To stop background sync from the same terminal: press Ctrl+X.
6. To fully quit: right-click the tray icon → Exit.

You are now production ready.

---

Quick cheat sheet (beginners)

What I want	What to do
Start the app	python FolderSync/main.py then press 1
Change where folders are created	Menu option 3
Change login / server	Menu option 2
Check Kitsu login	Menu option 4
Sync once right now	Menu option 5
Stop sync	Ctrl+X in the terminal
Open my project folders	Menu option 7
See log files	Menu option 8
Quit the menu	0 or q

---

Reference guide (all options & commands)

Starting the program

Always from the repository root, with the virtual environment activated:

python FolderSync/main.py

Command-line shortcuts

These skip the interactive menu:

Command	What it does
python FolderSync\main.py	Opens the interactive terminal menu (recommended)
python FolderSync\main.py --setup	Opens setup only (first-time wizard if needed)
python FolderSync\main.py --sync	Runs one sync in the console, then exits
python FolderSync\main.py --gui	Launches the tray/dashboard app directly
python FolderSync\main.py --help	Shows built-in help

Examples:

python FolderSync\main.py --setup
python FolderSync\main.py --sync
python FolderSync\main.py --gui

Notes:

• --gui and --sync require first-time setup to be finished already.
• During --sync or menu sync, press Ctrl+X to cancel.

---

Terminal menu options

When you run python FolderSync\main.py with no flags, you get this menu:

Key	Option	Description
1	Launch app	Opens dashboard + system tray and starts automatic sync
2	Setup config	Full settings: server, project root, credentials, poll interval, folder templates
3	Change project root	Change only the folder where projects are created
4	Test connection	Login to Kitsu and list visible projects
5	Run sync once	One full sync in the terminal (no GUI). Ctrl+X stops it
6	View configuration	Shows current settings (password is never printed)
7	Open project root folder	Opens the OS file manager at your project root
8	Open logs folder	Opens the logs directory
9	Clear stored password	Removes the password from the OS credential store
0 / q	Exit	Leaves the launcher

Header of the menu also shows:

• Server URL
• Project root
• Credential status
• Poll interval

---

Configuration explained

Settings are stored in config.json next to where you run the app (usually the repository root).

Important fields

Setting	Default	Meaning
server	http://kitsu.local:8012 (placeholder)	Kitsu / Zou server address — replace with your real URL
project_root	<repo>/projectRoot	Root folder where local projects are created
poll_interval	30	Seconds between automatic sync cycles
username	(your email)	Kitsu login email
password	null in file	Never stored in the JSON file when remember-login is on
api_token	null	Optional bot / API token (advanced)
remember_login	true recommended	Save password in the OS credential store
setup_complete	set after first setup	Blocks accidental sync before setup
folders	plates, comp, nuke, …	Subfolders created inside each shot

Passwords & security

• Passwords are stored with keyring (Windows Credential Manager, macOS Keychain, or Linux Secret Service).
• config.json keeps "password": null.
• Do not email or commit real passwords.
• Use menu option 9 to clear a stored password (for example when leaving a shared machine).

Changing the project root later

Anyone can change it anytime:

1. Run the app menu
2. Choose 3 Change project root
3. Enter the new path (or keep the studio default)

Or use 2 Setup config for a full settings pass.

---

What gets created on disk

Under your project root:

projectRoot/
  └── MyProject/
        ├── Assets/
        │     └── AssetName/
        │           ├── textures/
        │           ├── source/
        │           ├── publish/
        │           ├── renders/
        │           └── reference/
        ├── Shots/
        │     └── SH010/
        │           ├── plates/
        │           ├── comp/
        │           ├── nuke/
        │           ├── renders/...
        │           ├── README.txt
        │           ├── shot.json
        │           └── notes.txt
        ├── Sequences/
        ├── Editorial/
        ├── Delivery/
        ├── LUTs/
        └── Templates/

The app is safe to re-run: existing folders are not wiped. It creates what is missing.

---

Stopping sync with Ctrl+X

Situation	Ctrl+X does this
Menu option 5 / --sync	Cancels the current sync pass
Menu option 1 / --gui (terminal still open)	Stops background automatic sync

The GUI/tray can keep running after sync is stopped. Use the tray Exit item to close the app fully.

---

Logs & troubleshooting

Logs

• Folder: logs\
• Daily file example: logs\2026-08-03.log
• Open quickly with menu option 8

Common problems

“First-time setup required”
Run python FolderSync\main.py (no flags) or python FolderSync\main.py --setup.

Authentication failed
Use menu 2 to re-enter email/password, then 4 to test.

Folders not appearing

1. Confirm project root with menu 6.
2. Run menu 5 once.
3. Check you can see the project in Kitsu in a browser.
4. Read the latest file in logs/.

Cannot create the project root
Check disk permissions for projectRoot/, or choose another path with menu 3.

python / python3 not found
Install Python 3.12+ and ensure it is on PATH, then reopen the terminal.

Menu looks broken / weird characters
Use a modern UTF-8 terminal (Windows Terminal, GNOME Terminal, Konsole, etc.).

Linux tray icon missing
Install a StatusNotifier/AppIndicator host for your desktop, or keep using the dashboard window and console menu.

---

System tray (when app is launched)

After option 1 / --gui, the tray menu includes:

• Open Dashboard
• Sync Now
• Open Root Folder
• Settings (placeholder for future UI)
• View Log
• Exit

Most people can leave the dashboard closed and keep the tray icon only.

---

Developer / advanced notes

Project layout

kitsuProjectSync/
  config.json              # local settings (no password)
  folders.db               # sync state database
  logs/                    # rotating log files
  assets/                  # README screenshots
  FolderSync/
    main.py                # entry point
    config.py              # configuration + defaults
    requirements.txt
    api/                   # Kitsu client + credential helpers
    cli/                   # terminal menu, setup wizard, sync runner
    gui/                   # dashboard + tray
    sync/                  # synchronizer + folder creation
    database/              # SQLite
    utils/                 # logging, paths, platform helpers, Ctrl+X

Dependencies

Listed in FolderSync/requirements.txt:

• PySide6 — GUI / tray
• requests — Kitsu REST API
• keyring — OS credential store
• rich — terminal UI

Cross-platform notes

• Default sync folder is always <repository>/projectRoot.
• Paths use pathlib (no hard-coded OS separators in logic).
• Opening folders uses os.startfile / open / xdg-open.
• Ctrl+X works on Windows (msvcrt) and Linux/macOS (termios).
• Server URL defaults to a placeholder (http://kitsu.local:8012) — set the real URL in setup.

API behavior (short)

• Login: POST /api/auth/login → uses access_token
• Data: /api/data/projects, /sequences, /shots, /assets
• Token check: /api/auth/authenticated

Packaging (optional, IT)

A single .exe can be built later with PyInstaller (already listed in requirements). Until then, artists should use the Python + menu workflow above.

---

Support checklist for new workstations

Copy this for onboarding:

• Python 3.12+ installed
• Repo copied / cloned onto the machine
• .venv created and requirements installed
• projectRoot/ writable (or custom root configured)
• First-time setup completed (project root confirmed)
• Menu option 4 connection test OK
• Menu option 5 first sync OK
• Menu option 1 tray app running for the day

---

License / internal use

Internal studio tool for synchronizing Kitsu productions to local disk.
Ask your pipeline / IT lead before installing on unmanaged machines.