Circos > Documentation > Tutorials > Reference > Command Line
Circos at the EMBO NGS workshop in Tunis, Sept 15–25.

Use the latest version of Circos and read Circos best practices—these list recent important changes and identify sources of common problems.
If you are having trouble, post your issue to the Circos Google Group and include all files and detailed error logs. Please do not email me directly unless it is urgent—you are much more likely to receive a timely reply from the group.
Don't know what question to ask? Read Points of View: Visualizing Biological Data by Bang Wong, myself and invited authors from the Points of View series.

11 — Circos Reference

3. Command Line Parameters

using command-line flags

Circos is driven by a configuration file, but accepts several command-line flags that change how it runs (e.g. format and location of output files).

# no flags - Circos guesses location if configuration file
> circos

# specific configuration file
> circos -conf etc/circos-fig1.conf

# additional debugging
> circos -debug 

# additional debugging, by group
> circos -debug_group io,chrfilter

# brief usage
> circos -h

# man page
> circos -man

# version check
> circos -v

# module diagnostics
> circos -modules

# run and shut up
> circos -silent

Configuration flags can be shortened, as long as the shortened version is unambigous.

> circos -cdump image
> circos -cdum image
> circos -cdu image
> circos -cd image
# -c is not ok because it is 
> circos -c image
Option c is ambiguous (cdump, chromosomes, chromosomes_display_default, chromosomes_order, 
chromosomes_radius, chromosomes_scale, color_cache_rebuild, color_cache_static, configfile)

The -param flag allows you to conveniently change the value of any configuration parameter.

# change image size
> circos -param image/radius=2000p
# do not draw ideograms
> circos -param ideogram/show=no
# draw only two chromosomes
> circos -param chromosomes_display_default=no -param chromosomes=hs1;hs2

Circos command-line flags



-conf FILE
Name of configuration file.
DEFAULT circos.conf
Circos will attempt to guess the location of this file, searching in ., .. and ../... In other words
> circos
is equivalent to
> circos -conf etc/circos.conf.
> circos -debug_group +io
to include debug information about where files are being searched.

Sets the value of parameter PARAM in configuration path PATH to VALUE. You can use multiple -param flags. The PATH must point to a unique block. The flag can be used multiple times.
e.g. -param chromosomes=hs1
e.g. -param ideogram/show=no
e.g. -param ideogram/spacing/default=0.01r
e.g. -param a=10 -param b=20 -param c=30
This is useful for temporary override a configuration parameter, such as in a batch job were you are running Circos several times with different parameters. Within the configuration parameter, value of parameters can be referenced using conf().

-cdump [BLOCK1/[BLOCK2/...]][:REGEX]
Report a dump of the configuration. If BLOCK is specified, only show that block. To show nested blocks, specify a block path delimited by /. To limit the output to parameters that match a regular expression, include :REGEX
e.g. -cdump image
e.g. -cdump ideogram/spacing
e.g. -cdump ideogram/spacing:def



Display usage synopsis.

Show man page.

Print the version.



Obtain additional debugging.

-debug_group GROUP,[GROUP,...]
Toggle report of debug messages for various modules. Prefix the group with + to add to the default list, - to remove it. To show debuging from all groups, use _all. To get a list of groups, use the flag without an argument.
DEFAULT summary
e.g. -debug_group
e.g. -debug_group=+timer
e.g. -debug_group=-summary
e.g. -debug_group=+io,+png
e.g. -debug_group _all
If the image takes more than 30 seconds to generate, Circos will report timers for code components (group: timer). For reference, see the list of all debug groups. Groups with a + or - prefix require the use of = in the flag, otherwise they'll be interpreted as flags themselves.

-fakeerror GROUP,ERROR
Simulate error ERROR from error group GROUP.
e.g. -fakeerror
e.g. circos -fakeerror io

Diagnose required modules..
Success means that the module was found and successfully loaded.

Make all warnings fatal.
DEFAULT -paranoid
OPTION -noparanoid

Generate no runtime messages.

Report code timings.
Same as
> circos -debug_group=+timer

Report the version and quit.

Enable warnings.
DEFAULT -warnings
OPTION -nowarnings



-outputdir DIR
-dir DIR
Image output directory
e.g. -dir ..

-outputfile FILE
-file FILE
Output image filename. Can include a path. Extention (png, svg) will be automatically added.
DEFAULT circos
e.g. -file otherfile
e.g. -file ../otherfile
Extention .png or .svg will be added.

Create a PNG file.
OPTION -nopng

Create a SVG file.
OPTION -nosvg



Forces a rebuild of the color cache.
See etc/housekeeping.conf for color* parameters.

Forces the use of an existing color cache, even if colors have been redefined.
See etc/housekeeping.conf for color* parameters.

-randomcolor [COLOR1,COLOR2,...]
Generates an image in which all colors except for those listed are randomized.
e.g. -randomcolor white,black