Quick reference

Quick reference

Important Notes

• 🔑 Commands marked with 🔑 require authentication
• 📂 Commands marked with 📂 must be run from within a project directory
• ⚠️ Commands marked with ⚠️ require caution as they can delete or modify data
• 🌐 Commands marked with 🌐 interact with Claude.ai API

Detailed Command Reference

Authentication Commands 🌐

Command	Description	Context & Notes
claudesync auth login	Authenticate with Claude.ai	- Requires Claude Pro/Team subscription - Will prompt for session key from claude.ai - Use --session-key for CI/CD environments - Use --auto-approve to skip expiry confirmation
claudesync auth logout	Log out from all providers	- Removes all stored credentials - Cannot be undone
claudesync auth ls	List authenticated providers	- Shows active authentication status

Organization Management 🌐🔑

Command	Description	Context & Notes
claudesync organization set	Set active organization	- Required before project operations - Must be run after login - Organizations must have Claude Pro capability
claudesync organization ls	List available organizations	- Only shows organizations with required capabilities

Project Management 🌐🔑

Command	Description	Context & Notes
claudesync project create	Create new project	- Run in your project directory - Creates .claudesync directory - Default name is directory name - Creates local configuration
claudesync project set	Set active project	- Run in your project directory - Links directory to remote project - Use -a to see submodule projects
claudesync project ls	List projects	- Shows all accessible projects - Use -a to include archived projects
claudesync project archive ⚠️	Archive projects	- Cannot be undone - Use -a to archive all projects - Use -y to skip confirmation
claudesync project file ls 📂	List project files	- Must be run in project directory - Shows remote files
claudesync project truncate ⚠️	Delete all files	- Permanently deletes remote files - Cannot be undone - Use -y to skip confirmation

File Synchronization 🌐🔑📂

Command	Description	Context & Notes
claudesync push	Sync local files to remote	- Must be run in project directory - Respects .claudeignore - Default max file size: 32KB - Use --category for selective sync - Use --uberproject for submodule inclusion
claudesync sync schedule	Set up automated sync	- Creates cron job (Unix) or scheduled task (Windows) - Requires appropriate system permissions

Submodule Management 🌐🔑📂

Command	Description	Context & Notes
claudesync submodule ls	List detected submodules	- Must be run in main project directory - Detects based on submodule_detect_filenames
claudesync submodule create	Create projects for submodules	- Creates separate Claude.ai projects - Names format: {main_project}-SubModule-{submodule_name} - Updates local configuration

Chat Management 🌐🔑

Command	Description	Context & Notes
claudesync chat init	Create new chat	- Optionally link to project - Can set custom name - Returns chat UUID
claudesync chat message	Send chat message	- Streams response - Can specify timezone - Creates new chat if UUID not provided
claudesync chat ls	List chats	- Shows all chats for organization - Includes project associations
claudesync chat pull 📂	Sync chats and artifacts	- Downloads to claude_chats directory - Preserves artifacts and conversations - Must be run in project directory
claudesync chat rm ⚠️	Delete chats	- Cannot be undone - Use -a to delete all chats

Configuration Management 📂

Command	Description	Context & Notes
claudesync config ls	List all settings	- Shows both global and local settings - Local settings override global
claudesync config set	Update setting	- Some settings are global-only - Some require project directory
claudesync config get	View specific setting	- Shows effective value (local or global)

Category Management

Command	Description	Context & Notes
claudesync config category add	Add file category	- Globally available - Patterns use gitignore syntax
claudesync config category rm	Remove category	- Cannot remove built-in categories
claudesync config category update	Update category	- Can update description and patterns
claudesync config category ls	List categories	- Shows built-in and custom categories
claudesync config category set-default	Set default category	- Applied when no category specified

Configuration Settings

Global Settings

Setting	Description	Default	Notes
active_provider	Current API provider	claude.ai	Currently only claude.ai supported
log_level	Logging verbosity	INFO	Options: DEBUG, INFO, WARNING, ERROR
max_file_size	Maximum file size (bytes)	32768	Files larger are skipped
compression_algorithm	File compression	none	Options: none, zlib, brotli, bz2, lzma, pack
submodule_detect_filenames	Files indicating submodules	["pom.xml", "package.json", ...]	Used for submodule detection

Project-Specific Settings

Setting	Description	Default	Notes
active_organization_id	Selected organization ID	None	Set via organization set
active_project_id	Selected project ID	None	Set via project set/create
active_project_name	Selected project name	None	Set via project set/create
local_path	Local sync directory	Current dir	Set via project set/create
upload_delay	Delay between uploads (s)	0.5	Prevents rate limiting
two_way_sync	Enable bidirectional sync	false	Experimental feature
prune_remote_files	Auto-delete missing remote files	true	Set false to preserve remote

File Ignore Rules

Create a .claudeignore file in your project directory. Syntax matches .gitignore:

# Common ignore patterns
*.log
.env
node_modules/
__pycache__/
.git/
.idea/
venv/

Project Structure

your-project/
├── .claudesync/           # Created by claudesync
│   └── config.local.json  # Local project config
├── .claudeignore          # Optional ignore file
├── services/              # Optional submodules directory
│   ├── service1/
│   │   ├── pom.xml       # Submodule indicator
│   │   └── src/
│   └── service2/
│       ├── package.json  # Submodule indicator
│       └── src/
└── src/                  # Main project files

Common Workflows

Initial Project Setup

# Login
claudesync auth login

# Create project in current directory
cd your-project
claudesync project create

# Optional: Configure packing
claudesync config set compression_algorithm pack

# Initial sync
claudesync push

Working with Submodules

# From main project directory
cd your-project

# Check for submodules
claudesync submodule ls

# Create submodule projects
claudesync submodule create

# Sync including submodules
claudesync push --uberproject

# Or sync specific submodule
cd services/service1
claudesync push

Chat and Development

# Send message and get response in a standalone chat
claudesync chat message "Please review this code:"

# Save chat history and artifacts
claudesync chat pull