Command: gears sync

Synchronize your local .gears files with the mygears.dev cloud platform.

Overview

The sync command uploads (push) or downloads (pull) your .gears documentation between your local machine and the cloud. This enables backup, collaboration across machines, and team sharing of project documentation.

Syntax

run gears sync push          # Upload local files to cloud
run gears sync pull          # Download files from cloud
run gears sync push --force  # Force upload even if conflicts exist
run gears sync pull --force  # Force download and overwrite local files

Subcommands

`gears sync push`

Uploads your local .gears files to mygears.dev.

What gets pushed:

Session files (.gears/sessions/*.md)
Story files (.gears/story/*.md)
ADR files (.gears/adr/*.md)
Memory files (.gears/memory/**/*)
Context files (.gears/context/**/*)

What doesn't get pushed:

.gears/config.json (auth tokens stay local)
Files in .gitignore
Temporary or system files

`gears sync pull`

Downloads files from mygears.dev to your local machine.

Behavior:

New files are downloaded
Existing files are updated if cloud version is newer
Local-only files are preserved
Conflicts are detected and require manual resolution or --force

Authentication Required

Both push and pull require authentication. If not authenticated:

$ run gears sync push
Error: Not authenticated. Run 'gears auth' first

Run run gears auth first to authenticate.

Working with AI Agents

Always have your AI agent run sync commands for you. The output shows:

What files are being synced and where they're stored
How the synchronization system works
The relationship between local and cloud storage

Example:

❌ "I think my files are synced"
✅ "Run gears sync push and show me what was uploaded"

This helps the agent understand your documentation system and provide better file management assistance.

Examples

Push Files to Cloud

$ run gears sync push
Scanning .gears directory...
Found 12 files to sync

Uploading sessions/2026-03-25.md... ✓
Uploading story/story-user-authentication.md... ✓
Uploading adr/001-database-choice.md... ✓
Uploading memory/index.md... ✓

[OK] 12 files synced to cloud
View at: https://mygears.dev/files

Pull Files from Cloud

$ gears sync pull
Checking for updates from cloud...
Found 5 new/updated files

Downloading sessions/2026-03-24.md... ✓
Downloading story/story-email-notifications.md... ✓
Updating adr/002-api-auth.md... ✓

[OK] 5 files downloaded

Force Push (Overwrite Cloud)

Use when you're sure your local version is correct:

$ gears sync push --force
Warning: This will overwrite cloud files with local versions

Uploading all files...
[OK] 15 files force-pushed to cloud

Force Pull (Overwrite Local)

Use when you're sure the cloud version is correct:

$ gears sync pull --force
Warning: This will overwrite local files with cloud versions

Downloading all files...
[OK] 15 files force-pulled from cloud

Typical Daily Workflow

# Morning: Start work
gears sync pull          # Get latest from team
gears session            # Create today's session

# During day: Work on features
gears story new "Feature Name"
# ... do development work ...

# End of day: Backup and share
gears session            # Update today's session
gears sync push          # Share with team/backup

How Sync Works

File Tracking

Each file is tracked with:

Checksum (MD5) - Detects content changes
Modified timestamp - Tracks when file was last updated
File path - Relative to .gears/ directory
Version history - Cloud keeps previous versions

Conflict Detection

Conflicts occur when:

Same file modified locally and in cloud
Different content (checksums differ)
Timestamps don't match

Resolution options:

Manual merge - Review both versions and merge manually
Force push - Keep local version: --force flag
Force pull - Keep cloud version: --force flag

Example Conflict

$ gears sync push
Checking for conflicts...

⚠️  Conflict detected:
File: story/story-user-auth.md
Local:  Modified 2026-03-25 14:30
Cloud: Modified 2026-03-25 14:45

Options:
1. Force push (overwrite cloud): gears sync push --force
2. Force pull (overwrite local): gears sync pull --force
3. Resolve manually and push again

Sync Performance

Incremental Sync

Only changed files are transferred:

$ gears sync push
Scanning .gears directory...
Found 50 files total
12 files changed since last sync

Uploading 12 files... ✓
38 files already up to date

Large Projects

For projects with many files:

# First sync (uploads everything)
$ gears sync push
Uploading 500 files... (this may take a minute)
[OK] 500 files synced

# Subsequent syncs (only changes)
$ gears sync push
Uploading 3 files... ✓
[OK] 3 files synced, 497 unchanged

Security and Privacy

What's Stored

Files are stored on mygears.dev with:

✅ HTTPS encryption in transit (TLS 1.3)
✅ Encryption at rest (AES-256)
✅ Access controlled by API tokens
✅ Version history for recovery

Token Storage

Your auth token stays local:

Stored in .gears/config.json
Never uploaded to cloud
Add to .gitignore to avoid committing

Data Privacy

Files are private to your account
Team access requires shared project tokens
Token abilities control read/write permissions
You can delete files anytime from mygears.dev

Team Collaboration

Workflow for Teams

# Team Member 1 (morning)
gears sync pull         # Get latest team docs
gears session           # Start daily session
# ... work on features ...
gears sync push         # Share progress

# Team Member 2 (afternoon)
gears sync pull         # Gets Team Member 1's updates
gears session           # Continue work
# ... work on features ...
gears sync push         # Share progress

# Both team members stay in sync

Conflict Resolution Strategy

Prevention:

Sync frequently (start and end of day minimum)
Communicate when working on shared files
Use feature branches if using Git

When conflicts occur:

Pull latest: gears sync pull
Review differences manually
Merge changes locally
Push merged version: gears sync push

Shared Project Setup

Project owner initializes:
```
gears init
gears auth
gears sync push
```

Team members join:

git clone <repo>      # Get codebase
gears auth            # Auth with own account
gears sync pull       # Download shared .gears files

Monitoring Sync Activity

View Files in Cloud

Visit https://mygears.dev/files to:

See all your synced files
View file contents
Check sync timestamps
Download individual files
Delete files if needed

Sync History

Visit https://mygears.dev/activities to:

See sync activity log
Track when files were pushed/pulled
View who synced what (in team setups)
Audit file changes

Troubleshooting

Authentication Failed

Problem:

$ gears sync push
Error: Authentication failed
Token may be expired or invalid

Solution:

# Re-authenticate
gears auth logout
gears auth

# Try sync again
gears sync push

Network Connection Error

Problem:

$ gears sync push
Error: Could not connect to mygears.dev
Check your internet connection

Solutions:

Check internet connectivity
Verify mygears.dev is accessible: curl https://mygears.dev
Check firewall settings
Try again later (may be temporary)

Sync Stuck or Slow

Problem: Sync taking very long time

Solutions:

# Check how many files need syncing
ls -R .gears/ | wc -l

# Large first sync is normal
# Subsequent syncs should be fast (incremental)

# If stuck, cancel and retry
# Ctrl+C to cancel
gears sync push

File Not Syncing

Problem: Specific file not appearing in cloud

Solutions:

Check file exists locally: ls .gears/path/to/file.md
Check file permissions: ls -la .gears/path/to/file.md
Try force push: gears sync push --force
Check mygears.dev for any error messages

Incorrect File Version

Problem: Wrong version of file in cloud

Solution:

# Option 1: Force push your local version
gears sync push --force

# Option 2: Download cloud version and compare
gears sync pull --force
# Review the file
# Make necessary changes
gears sync push

Large File Warning

Problem: File too large to sync

Warning: File too large: memory/large-dataset.csv (15MB)
Max file size: 10MB

Solution:

Large data files shouldn't be in .gears/
Use .gitignore to exclude: echo "*.csv" >> .gears/.gitignore
Store large files elsewhere (S3, Git LFS, etc.)

Best Practices

Sync Frequency

Recommended:

📤 Push: End of day, after significant work, before leaving
📥 Pull: Start of day, after lunch, before major changes

Minimum:

Push at least daily
Pull before starting work

Optimal for teams:

Push after each feature/story completion
Pull multiple times per day

What to Commit to Git vs Sync to Cloud

.gears files:

✅ Commit to Git (team versioning)
✅ Sync to cloud (backup, cross-machine)

Why both?

Git: Version control, pull requests, code review
Cloud: Backup, easy access without cloning, web interface

Automation (Advanced)

# Git hooks: Auto-sync on commit
# .git/hooks/post-commit
#!/bin/bash
gears sync push

# Cron job: Auto-pull every hour
0 * * * * cd /path/to/project && gears sync pull

Related Commands

gears auth - Required before syncing
gears init - Creates .gears directory to sync
gears session - Create files to sync
gears story - Create stories to sync
gears adr - Create ADRs to sync

Next Steps

After syncing:

Verify on web: Visit https://mygears.dev/files to see your files
Check activity log: Visit https://mygears.dev/activities
Setup regular syncing: Make it part of your daily routine
Team onboarding: Share sync workflow with team members

← Command: adr | Command: completion →