CLI Tutorial

Run SynapSpec from the command line with the same main settings available in the GUI.

Installation & Running CLI

Linux

Extract the tar archive and run:

./synapspec run config.yaml

macOS

After installation, run from the terminal:

/Applications/SynapSpec.app/Contents/MacOS/synapspec run config.yaml

You can also add an alias to your shell profile:

alias synapspec='/Applications/SynapSpec.app/Contents/MacOS/synapspec'

Then run:

synapspec run config.yaml

Windows

Note: CLI is not supported on Windows. Please use the GUI application instead.

Command

synapspec run config.yaml

Useful options:

Option Description
--debug Show verbose logs for troubleshooting.
--no-track Disable anonymous usage analytics.
--keep-intermediates Keep intermediate files for debugging or resume workflows.

Configuration File

The CLI uses a YAML file. This page lists the same main settings exposed on the New Analysis page, not every internal advanced parameter.

Use this when you want SynapSpec to generate a spectral library from FASTA files.

ms_files:
  - path: /data/control_01.raw
    condition: Control
    replication: 1
  - path: /data/control_02.raw
    condition: Control
    replication: 2
  - path: /data/treatment_01.raw
    condition: Treatment
    replication: 1
  - path: /data/treatment_02.raw
    condition: Treatment
    replication: 2

output_directory: /data/synapspec_output

general:
  n_cores: 8
  run_mbr: true
  use_hardware_acceleration: true

library:
  fasta_files:
    - /data/uniprot_human.fasta
  generate: true
  enzyme: trypsin/p
  include_met_loss: true
  cleavage_mode: specific
  fixed_modifications: Carbamidomethyl@C
  variable_modifications: Oxidation@M;Acetyl@Protein_N-term
  max_var_mod_num: 2
  missed_cleavages: 1
  precursor_length_range: [7, 35]
  precursor_charge_range: [2, 4]
  fragment_types: b;y
  search_strategy: dynamic

fdr:
  fdr: 0.01
  protein_fdr: 0.01

output:
  file_format: csv
  min_correlation: 0.9
  peptide_level_lfq: false
  precursor_level_lfq: false
  differential_analysis:
    enabled: true
    condition_aware_precursor_correction: true
    quantity_level: pg

Use this when you already have a spectral library. In this mode, digestion and modification settings are not needed.

ms_files:
  - path: /data/control_01.raw
    condition: Control
    replication: 1
  - path: /data/control_02.raw
    condition: Control
    replication: 2
  - path: /data/treatment_01.raw
    condition: Treatment
    replication: 1
  - path: /data/treatment_02.raw
    condition: Treatment
    replication: 2

output_directory: /data/synapspec_output

general:
  n_cores: 8
  run_mbr: true
  use_hardware_acceleration: true

library:
  library_file: /data/library.txt
  generate: false

fdr:
  fdr: 0.01
  protein_fdr: 0.01

output:
  file_format: csv
  min_correlation: 0.9
  peptide_level_lfq: false
  precursor_level_lfq: false
  differential_analysis:
    enabled: true
    condition_aware_precursor_correction: true
    quantity_level: pg

GUI Setting Mapping

Files

GUI setting YAML key
Input files ms_files
Condition ms_files[].condition
Replication ms_files[].replication
FASTA files library.fasta_files
Library file library.library_file

Each ms_files entry is an object with path and optional condition and replication metadata. Condition and replication are required when differential analysis is enabled. Replication must be a positive whole number.

Use the same replication number for technical runs from the same biological replicate. Differential analysis requires at least two conditions, and each input file must have a unique filename.

Library

GUI setting YAML key
Enzyme library.enzyme
Custom Cleavage Rule library.custom_cleavage_rule
Include initiator methionine loss library.include_met_loss
Cleavage Mode library.cleavage_mode
Search Strategy library.search_strategy
Fixed Modifications library.fixed_modifications
Variable Modifications library.variable_modifications
Max Variable Modification Number library.max_var_mod_num
Missed Cleavages library.missed_cleavages
Precursor Length Range library.precursor_length_range
Precursor Charge Range library.precursor_charge_range
Fragment Types library.fragment_types

Supported cleavage mode values are specific, specific-n, specific-c, semi-specific, and unspecific.

To define a custom enzyme from the CLI, set library.enzyme to custom and provide the cleavage rule as a regular expression. For example, this rule cleaves after K or R unless the next residue is P:

library:
  enzyme: custom
  custom_cleavage_rule: "(?<=[KR])(?!P)"
GUI setting YAML key
FDR Cutoff (%) fdr.fdr
Protein FDR Cutoff fdr.protein_fdr
Search Mode library.n_glyco
N-Glyco Allowed Precursor Charges library.n_glyco.allowed_charges
N-Glyco Max Missed Cleavages library.n_glyco.max_missed_cleavages
Run MBR general.run_mbr

The GUI shows FDR as a percentage. In YAML, use the decimal value: 1% in the GUI is 0.01 in the config.

For conventional proteomics, omit library.n_glyco. For Glyco Proteomics mode, add:

library:
  n_glyco:
    allowed_charges: [3, 4, 5, 6, 7]
    max_missed_cleavages: 2

Compute

GUI setting YAML key
Number of CPU cores general.n_cores
Hardware Acceleration general.use_hardware_acceleration

Log Verbose is controlled from the CLI with --debug, and analytics tracking is controlled with --no-track.

Output

GUI setting YAML key
Output directory output_directory
File Format output.file_format
Minimum Correlation output.min_correlation
Peptide Level LFQ output.peptide_level_lfq
Precursor Level LFQ output.precursor_level_lfq
Enable Differential Analysis output.differential_analysis.enabled
Condition-aware Precursor Correction output.differential_analysis.condition_aware_precursor_correction
Differential Analysis Quantity Level output.differential_analysis.quantity_level

The GUI shows minimum correlation as a percentage. In YAML, use the decimal value: 90% in the GUI is 0.9 in the config.

Differential analysis supports pg (protein group), precursor, and peptide quantity levels. The default is pg. When using peptide, also set output.peptide_level_lfq: true.

Condition-aware precursor correction improves the MS2 quantities used for differential analysis by accounting for condition-specific protein-level information. Set output.differential_analysis.enabled: false to disable differential analysis; condition and replication metadata may then be omitted.

Notes

  • Choose one input source: either library.library_file or library.fasta_files.
  • Set library.generate: true when using FASTA files.
  • Set library.generate: false when using an existing library file.
  • Keep advanced/internal config keys out of your YAML unless instructed by support.