CLI Tutorial

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 in the GUI wizard, not every internal advanced parameter.

Minimal FASTA Search

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

Library Search

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

Step 1 — 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.

Step 2 — Method

The Method step groups Library Generation Settings, FDR Settings, and General Settings.

Library Generation Settings

GUI setting	YAML key
Enzyme	library.enzyme
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.

FDR Settings

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

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

General Settings

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

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

Step 3 — 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.