> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filefetch.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start Guide

> Get started with FileFetch in 5 minutes

## Prerequisites

Before you begin, make sure you have:

<Steps>
  <Step title="Salesforce Account">
    Active Salesforce account with login credentials (username, password, and security token)
  </Step>

  <Step title="System Requirements">
    * **macOS**: 10.15 (Catalina) or later
    * **Windows**: Windows 10 or later
  </Step>

  <Step title="File Access">
    Salesforce user permissions to view and download files
  </Step>
</Steps>

## Step 1: Download & Install

<Tabs>
  <Tab title="macOS">
    1. Download FileFetch for macOS from [filefetch.app/download](https://filefetch.app/download)
    2. Open the downloaded `.dmg` file
    3. Drag FileFetch to your Applications folder
    4. Launch FileFetch from Applications

    <Note>
      On first launch, you may need to **right-click → Open** to bypass macOS Gatekeeper if you see a security warning.
    </Note>
  </Tab>

  <Tab title="Windows">
    1. Download FileFetch for Windows from [filefetch.app/download](https://filefetch.app/download)
    2. Run the `.exe` installer
    3. Follow the installation wizard
    4. Launch FileFetch from your Start Menu or Desktop

    <Note>
      Windows SmartScreen may show a warning for new apps. Click **More info → Run anyway** to proceed.
    </Note>
  </Tab>
</Tabs>

## Step 2: Connect to Salesforce

When you first launch FileFetch, you'll see the login screen.

<Steps>
  <Step title="Select Environment">
    Choose your Salesforce environment:

    * **Production** - For live Salesforce orgs (login.salesforce.com)
    * **Sandbox** - For test/dev environments (test.salesforce.com)
    * **Custom Domain** - For My Domain or custom URLs
  </Step>

  <Step title="Enter Credentials">
    Fill in your Salesforce credentials:

    ```
    Username: your-email@company.com
    Password: YourPassword
    Security Token: YourSecurityToken
    ```

    <Tip>
      Don't have a security token? [Reset it in Salesforce](https://help.salesforce.com/s/articleView?id=sf.user_security_token.htm) under **Settings → My Personal Information → Reset Security Token**.
    </Tip>
  </Step>

  <Step title="Sign In">
    Click **Sign In** to authenticate

    Your credentials are stored securely in your system keychain and never leave your computer.
  </Step>
</Steps>

## Step 3: Run Your First Query

Once logged in, you'll see the **Query & Export** page.

<Steps>
  <Step title="Choose Export Type">
    Select what to export in the **Export Configuration** panel:

    * **Files** (ContentVersion) - Modern Salesforce Files
    * **Attachments** - Legacy attachments
  </Step>

  <Step title="Set Filters (Optional)">
    Use Quick Filters to narrow your search:

    * **Date Range**: Last 7 days, Last 30 days, This Year, etc.
    * **File Type**: PDFs, Word documents, Excel, Images
    * **File Size**: Small (\<1MB), Medium (1-10MB), Large (>10MB)
    * **Related Object**: Filter by Account, Contact, Opportunity, etc.

    <Info>
      In Simple Mode, these filters automatically generate a SOQL query for you. The query preview shows exactly what will run.
    </Info>
  </Step>

  <Step title="Run Query">
    Click **Run Query** (or press `⌘/Ctrl + Enter`)

    FileFetch will fetch matching files from Salesforce and display them in the results table.
  </Step>
</Steps>

## Step 4: Export Files

<Steps>
  <Step title="Select Files">
    In the results table:

    * **Select individual files** by clicking checkboxes
    * **Select all** with the header checkbox
    * Review file details: Title, Extension, Size, Created Date
  </Step>

  <Step title="Configure Export">
    In the **Export Configuration** panel, set your preferences:

    * **Group by Related Record**: Organize files into folders by parent object
    * **File Naming**: Use real file names or Record IDs
    * **Duplicate Handling**: Append ID or skip duplicates
  </Step>

  <Step title="Start Export">
    Click **Export Selected Files**

    FileFetch will:

    1. Create a timestamped folder in your default export directory
    2. Download files concurrently (up to 10 at a time)
    3. Generate an export summary report
    4. Show progress with real-time updates
  </Step>

  <Step title="View Results">
    When complete, click **Open Folder** to view your exported files

    You'll find:

    * All downloaded files organized by your settings
    * `_Export_Summary.txt` with detailed export information
  </Step>
</Steps>

## What's Next?

<CardGroup cols={2}>
  <Card title="Advanced Querying" icon="code" href="/power-mode">
    Learn to write custom SOQL queries in Power Mode
  </Card>

  <Card title="CSV Import" icon="file-csv" href="/csv-import">
    Bulk select files by uploading a CSV with file IDs
  </Card>

  <Card title="Export History" icon="clock-rotate-left" href="/export-history">
    Track and retry past exports
  </Card>

  <Card title="Settings" icon="gear" href="/settings">
    Customize download behavior and preferences
  </Card>
</CardGroup>

## Common First-Time Issues

<AccordionGroup>
  <Accordion title="Invalid username, password, security token, or user locked out">
    **Solution**: Verify your credentials are correct. If using a security token, make sure it's appended to your password without spaces. If your account is locked, contact your Salesforce administrator.
  </Accordion>

  <Accordion title="No files showing up after query">
    **Solution**:

    * Check that files exist in your Salesforce org matching your filters
    * Verify you have permission to view files
    * Try removing filters to see all files
    * Make sure you're exporting the correct type (Files vs Attachments)
  </Accordion>

  <Accordion title="Download fails with 'timeout' error">
    **Solution**:

    * Increase timeout in Settings → Download Timeout (default: 120 seconds)
    * Check your internet connection
    * Try reducing concurrent downloads in Settings
  </Accordion>
</AccordionGroup>

<Tip>
  Need more help? Check out our [Troubleshooting Guide](/troubleshooting) or [contact support](mailto:support@filefetch.app).
</Tip>