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

# Sign Project

> Code sign your Native Desktop application for Windows and macOS

The `sign` command allows you to digitally sign your built Native Desktop applications for Windows and macOS. Code signing is essential for ensuring user trust, preventing security warnings, and meeting platform distribution requirements.

## Prerequisites

Before signing your application, ensure:

* Your application has been built using `native-desktop build`
* You have valid code signing certificates for your target platform
* You have the necessary credentials and identities configured

<Warning>
  Code signing requires platform-specific certificates and credentials. Unsigned applications may trigger security warnings or be blocked by operating systems.
</Warning>

## Basic Usage

To sign an application, run:

```shellscript theme={null}
native-desktop sign [app-path]
```

If you don't specify an app path, the CLI will attempt to detect the application automatically from the `bin/` directory.

```shellscript theme={null}
# Auto-detect application
native-desktop sign

# Specify application path
native-desktop sign bin/my-app.dmg
```

## Command Options

### `[app-path]` (Optional)

Path to the application to sign.

* **Type**: String (positional argument)
* **Required**: No (auto-detected if not provided)
* **Example**: `bin/MyApp.dmg`, `bin/MyApp.exe`

```shellscript theme={null}
native-desktop sign bin/MyApp.dmg
```

### `--platform`

Target platform for signing.

* **Type**: String
* **Choices**: `windows`, `mac`
* **Required**: No (auto-detected from app path)

```shellscript theme={null}
native-desktop sign --platform mac
```

### `--verbose`

Enable verbose logging for detailed signing information.

* **Type**: Boolean
* **Default**: `false`

```shellscript theme={null}
native-desktop sign --verbose
```

## macOS Signing

Signing macOS applications requires an Apple Developer certificate and optionally Apple ID credentials for notarization.

### Required Credentials

* **Developer ID Application Certificate**: For signing the application
* **Apple ID** (optional): For notarization
* **Team ID** (optional): For notarization

### macOS Options

#### `--identity`

Certificate identity name or hash for signing.

```shellscript theme={null}
native-desktop sign bin/MyApp.dmg --platform mac --identity "Developer ID Application: Your Name (TEAM123)"
```

* **Type**: String
* **Required**: Yes (for macOS)
* **Format**: Certificate name or SHA-1 hash

<Info>
  To find your certificate identity, use: `security find-identity -v -p codesigning`
</Info>

#### `--apple-id`

Apple ID email address for notarization.

```shellscript theme={null}
native-desktop sign bin/MyApp.dmg \
  --platform mac \
  --identity "Developer ID Application" \
  --apple-id "developer@example.com"
```

* **Type**: String
* **Required**: No (required for notarization)

#### `--apple-id-password`

Apple ID app-specific password for notarization.

```shellscript theme={null}
native-desktop sign bin/MyApp.dmg \
  --platform mac \
  --identity "Developer ID Application" \
  --apple-id "developer@example.com" \
  --apple-id-password "xxxx-xxxx-xxxx-xxxx"
```

* **Type**: String
* **Required**: No (required for notarization)

<Tip>
  Generate an app-specific password at [appleid.apple.com](https://appleid.apple.com). Never use your main Apple ID password.
</Tip>

#### `--team-id`

Apple Team ID for notarization.

```shellscript theme={null}
native-desktop sign bin/MyApp.dmg \
  --platform mac \
  --identity "Developer ID Application" \
  --apple-id "developer@example.com" \
  --apple-id-password "xxxx-xxxx-xxxx-xxxx" \
  --team-id "TEAM123456"
```

* **Type**: String
* **Required**: No (required for notarization)

### macOS Examples

#### Basic Signing (No Notarization)

```shellscript theme={null}
native-desktop sign bin/MyApp.dmg \
  --platform mac \
  --identity "Developer ID Application: Company Name (TEAMID)"
```

#### Signing with Notarization

```shellscript theme={null}
native-desktop sign bin/MyApp.dmg \
  --platform mac \
  --identity "Developer ID Application: Company Name (TEAMID)" \
  --apple-id "developer@example.com" \
  --apple-id-password "xxxx-xxxx-xxxx-xxxx" \
  --team-id "TEAMID"
```

#### Using Certificate Hash

```shellscript theme={null}
# Find certificate hash
security find-identity -v -p codesigning

# Sign using hash
native-desktop sign bin/MyApp.dmg \
  --platform mac \
  --identity "ABC123DEF456..."
```

### macOS Notarization

Notarization is an additional security step required for distribution outside the Mac App Store. It involves:

1. **Signing**: Application is signed with Developer ID
2. **Upload**: Binary is uploaded to Apple for scanning
3. **Verification**: Apple verifies the application
4. **Stapling**: Notarization ticket is attached to the application

<Note>
  Notarization is required for macOS 10.15+ applications distributed outside the Mac App Store.
</Note>

## Windows Signing

Signing Windows applications requires a code signing certificate in `.pfx` or `.p12` format.

### Required Credentials

* **Code Signing Certificate**: `.pfx` or `.p12` file
* **Certificate Password**: Password for the certificate file

### Windows Options

#### `--cert-file`

Path to the certificate file (`.pfx` or `.p12`).

```shellscript theme={null}
native-desktop sign bin/MyApp.exe \
  --platform windows \
  --cert-file "path/to/certificate.pfx" \
  --cert-password "your-password"
```

* **Type**: String
* **Required**: Yes (one of cert-file or certificate-sha1)

#### `--cert-password`

Password for the certificate file.

```shellscript theme={null}
native-desktop sign bin/MyApp.exe \
  --platform windows \
  --cert-file "certificate.pfx" \
  --cert-password "SecurePassword123"
```

* **Type**: String
* **Required**: Yes (when using cert-file)

<Warning>
  Never commit certificate passwords to version control. Use environment variables or secure secret management.
</Warning>

#### `--cert-subject-name`

Certificate subject name (alternative to cert-file).

```shellscript theme={null}
native-desktop sign bin/MyApp.exe \
  --platform windows \
  --cert-subject-name "Company Name Inc."
```

* **Type**: String
* **Required**: No

#### `--certificate-sha1`

Certificate SHA1 hash (alternative to cert-file).

```shellscript theme={null}
native-desktop sign bin/MyApp.exe \
  --platform windows \
  --certificate-sha1 "ABC123DEF456..."
```

* **Type**: String
* **Required**: No

### Windows Examples

#### Signing with Certificate File

```shellscript theme={null}
native-desktop sign bin/MyApp.exe \
  --platform windows \
  --cert-file "certificate.pfx" \
  --cert-password "MyPassword123"
```

#### Signing with Certificate Store

```shellscript theme={null}
native-desktop sign bin/MyApp.exe \
  --platform windows \
  --cert-subject-name "Company Name Inc."
```

#### Signing with SHA1 Hash

```shellscript theme={null}
native-desktop sign bin/MyApp.exe \
  --platform windows \
  --certificate-sha1 "1234567890ABCDEF1234567890ABCDEF12345678"
```

#### Signing MSI Installer

```shellscript theme={null}
native-desktop sign bin/MyApp.msi \
  --platform windows \
  --cert-file "certificate.pfx" \
  --cert-password "MyPassword123" \
  --verbose
```

## Automatic Signing During Build

You can automatically sign your application during the build process using the `--sign` flag:

```shellscript theme={null}
# macOS
native-desktop build --target dmg --sign

# Windows
native-desktop build --target exe --sign
```

<Info>
  When using `--sign` with the build command, signing credentials must be configured in your `native-desktop.config.json5` file.
</Info>

## Configuration File Signing

You can configure signing credentials in your `native-desktop.config.json5` file:

```json theme={null}
{
  "signing": {
    "mac": {
      "identity": "Developer ID Application: Company (TEAMID)",
      "appleId": "developer@example.com",
      "appleIdPassword": "xxxx-xxxx-xxxx-xxxx",
      "teamId": "TEAMID"
    },
    "windows": {
      "certFile": "path/to/certificate.pfx",
      "certPassword": "${WINDOWS_CERT_PASSWORD}"
    }
  }
}
```

<Tip>
  Use environment variables for sensitive credentials like passwords.
</Tip>

## Verification

After signing, verify your application:

### macOS Verification

```shellscript theme={null}
# Verify signature
codesign --verify --verbose bin/MyApp.app

# Check notarization
spctl --assess --verbose bin/MyApp.app

# Display signature information
codesign -dv bin/MyApp.app
```

### Windows Verification

```shellscript theme={null}
# Using signtool (Windows SDK)
signtool verify /pa bin/MyApp.exe

# Display signature information
signtool verify /v bin/MyApp.exe
```

## Common Issues

<AccordionGroup>
  <Accordion title="macOS: Certificate Not Found">
    **Error**: `Certificate identity not found`

    **Solution**: Ensure your Developer ID certificate is installed in Keychain.

    ```shellscript theme={null}
    # List available certificates
    security find-identity -v -p codesigning

    # Import certificate if needed
    security import certificate.p12 -k ~/Library/Keychains/login.keychain
    ```
  </Accordion>

  <Accordion title="macOS: Notarization Failed">
    **Error**: `Notarization failed`

    **Solution**: Check that all credentials are correct and the app-specific password is valid.

    * Verify Apple ID credentials
    * Ensure app-specific password is generated
    * Check Team ID matches your developer account
    * Review verbose logs with `--verbose`
  </Accordion>

  <Accordion title="Windows: Certificate Password Invalid">
    **Error**: `Invalid certificate password`

    **Solution**: Verify the certificate password is correct.

    ```shellscript theme={null}
    # Test certificate
    certutil -dump certificate.pfx
    ```
  </Accordion>

  <Accordion title="Windows: Certificate File Not Found">
    **Error**: `Certificate file not found`

    **Solution**: Provide the correct path to the certificate file.

    ```shellscript theme={null}
    # Use absolute path
    native-desktop sign bin/MyApp.exe \
      --cert-file "/absolute/path/to/certificate.pfx" \
      --cert-password "password"
    ```
  </Accordion>

  <Accordion title="Application Path Not Found">
    **Error**: `Application path not found`

    **Solution**: Ensure the application has been built and the path is correct.

    ```shellscript theme={null}
    # Build first
    native-desktop build --target dmg

    # Then sign
    native-desktop sign bin/MyApp.dmg
    ```
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Secure Credentials" icon="lock">
    Never commit certificates or passwords to version control. Use environment variables or secret management tools.
  </Card>

  <Card title="App-Specific Passwords" icon="key">
    Use Apple app-specific passwords instead of your main Apple ID password for notarization.
  </Card>

  <Card title="Certificate Protection" icon="shield">
    Store certificate files securely and restrict access to authorized personnel only.
  </Card>

  <Card title="Regular Renewal" icon="rotate">
    Monitor certificate expiration dates and renew before expiry to avoid distribution issues.
  </Card>
</CardGroup>

## Platform Requirements

### macOS

* **macOS 10.13+**: Required for code signing
* **Xcode Command Line Tools**: Install with `xcode-select --install`
* **Apple Developer Account**: Required for Developer ID certificates
* **Internet Connection**: Required for notarization

### Windows

* **Windows 7+**: Supported for code signing
* **signtool**: Included in Windows SDK
* **Code Signing Certificate**: From trusted Certificate Authority

## CI/CD Integration

### GitHub Actions Example

```yaml theme={null}
name: Build and Sign

on: [push]

jobs:
  build-mac:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install certificates
        env:
          CERTIFICATE_BASE64: ${{ secrets.MACOS_CERTIFICATE }}
        run: |
          echo $CERTIFICATE_BASE64 | base64 --decode > certificate.p12
          security import certificate.p12 -k ~/Library/Keychains/login.keychain
      
      - name: Build and Sign
        env:
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
          TEAM_ID: ${{ secrets.TEAM_ID }}
        run: |
          native-desktop build --target dmg
          native-desktop sign bin/MyApp.dmg \
            --platform mac \
            --identity "Developer ID Application" \
            --apple-id "$APPLE_ID" \
            --apple-id-password "$APPLE_PASSWORD" \
            --team-id "$TEAM_ID"
```