ncid - Man Page

Network Caller ID Client


ncid [options] [arguments]


[--alt-date               | -A]
[--call-log               | -c]
[--debug                  | -D]
[--delay <seconds>        | -d <seconds>]
[--help                   | -h]
[--hostname-flag          | -H]
[--log-enable <0|1>       | -l <0|1|2>]
[--log-dir <directory>    | -L <directory>]
[--module <module name>   | -m <module name>]
[--noexit                 | -X]
[--pidfile <file>         | -p <file>]
[--PopupTime <0-5>        | -t <0-5 seconds>]
[--ring <0-9|-1|-2|-3|-9> | -r <0-9|-1|-2|-3|-9>]
[--verbose <1-9>          | -v <1-9>]
[--version                | -V]
[--wakeup                 | -W]




The ncid client displays Caller ID information sent to it by the NCID server. In the default GUI mode, if the server is configured to send the Call Log, it will load the call log in the call history window at startup.  The history window is then updated by ncid whenever a call is received.

The minimum size of the client window at startup displays 8 columns and 5 rows in the history window. The user can resize the window bigger, but not smaller than the minimum size. The user can select which columns to display in the history window, but must select at least 3 columns.

The history window displays one line per call or message in columns. Each line starts with a line label and has a context menu.  Column headers and most line columns have a tooltip to display more information. The help menu displays information about each topic listed.

The view window shows all Line Types that can appear in the history window.  The view window also shows all LineIDS that do appear in the history window. The view menu can select Line Types and LineIDS for viewing.  Those not selected have a horizontal line through them.

The message window will send a user typed single line message to the server which, in turn, will send it to all connected clients.

The ncid client supports three themes:


Color theme on a white background.


Color theme on a black background.


Black and white theme.

The ncid client supports multiple languages.  Supported languages are in the Help menu.  The default language is English.

The ncid client runs on Linux, Windows and Mac OS X.  If ncid is given the --no-gui option, it will run without a GUI.

If ncid is given the --module <module name> option, it will output to either an external program or output module.  The ncid client can be configured to call any single module.  It cannot call multiple modules, but multiple clients can be used, each calling a different output module.

If ncid is configured to output to an external program, it will test for it and if it is not found, or if it is not executable, it will terminate with an error message.

The default configuration file for ncid is /etc/ncid/ncid.conf.

The distributed output modules are listed in the ncid_modules man page. They are customized as needed in the /etc/ncid/conf.d/ncid-<module name>.conf files.

Whenever the server connection is broken, ncid will normally try to reconnect every 15 seconds.  It provides a visual indication of the countdown and number of tries. If the delay between attempts is set to zero seconds, ncid will not attempt a reconnect.



Do not display CID information using a GUI.

Default: display CID using a GUI

--alt-date | -A

Display the date in an alternate format. Assuming the date separator is a "/", the date is displayed as dd/mm/yyyy.

Default: display the date as mm/dd/yyyy

--call-log | -c

Configure ncid to tell the server to send the call log.  Only used in the NoGUI mode.

Default: the call log is not sent

--debug | -D

Debug mode.  Displays all log messages sent to the client logfile.

Default: Verbose 3

--delay <seconds> | -D <seconds>

If <seconds> > 0, delay <seconds> between server connection attempts.

If <seconds> = 0, only one attempt to reconnect to server will be made.

Default: 15 seconds

--help | -h

Display usage.

--hostname-flag | -H

Changes the LINE field to <hostname>:ncid for created messages and adds <hostname> to the IDENT string

Default LINE field: ncid

--log-enable | -l

LogEnable can be set from 0-2.

If LogEnable = 0:
   * do not write to log file (disabled)

If LogEnable = 1:
   * embed process ID xxx in log file name: ncid-xxx.log

If LogEnable = 2:
   * overwrite log file
   * Use the OS name or hostname in log file name: ncid-<OS|hostname>.log
   * Be careful you don't launch multiple processes or they will step on each other!

Default: 2

--log-dir | -L

Set the directory for log files. It can be an absolute or relative path. A relative path should only be used when the ncid.conf file is in the same directory as the running client script, an indication the client is running on a limited OS, e.g. Android.


set LogDir "/tmp/logs"
set LogDir "logs"

Default:   $HOME/NCID/client

--module <module name> | -m <module name>

Output the Caller ID information to the external program or output module. <module name> is the name of the output module (program) to use. The selected module is sent all calls and messages.

Default module PATH: /usr/share/ncid/modules

--noexit | -X

Configure ncid to ignore the close window button.

--pidfile | -p

Name of PID file to create. Set to /var/run/ in an rc or init script when used as a service. Set to /var/run/<module name>.pid in an rc or init script when used as a service and when using a output module. There is no default.  If pidfile is not set, no pid file will be used.

--PopupTime <seconds> | -t <seconds>

Time the popup is forced to stay on top of all windows. Range is 1 second to 5 seconds, or 0 to disable.

Default popup time: 1 second

--ring <count> | -r <count>
Execute output module on specific ring count.
All count values: -9 -3 -2 -1 0 2 3 4 5 6 7 8 9
For modems that indicate RING, count can be: -9 0 2 3 4 5 6 7 8 9
A count of -9 executes the output module on each ring.
A count of 0 executes the output module when ringing stops.
A count of 1 should never be used in the US/Canada,
because Caller ID is sent between rings 1 and 2.
A count between 2-9 executes the output module on that ring number.
A count greater than 9 is not useful.
For VoIP, using a SIP gateway, count is: -3 -2 -1
For POTS, using a wc2ncid gateway, count is: -2 -1
A count of -1 executes the output module on call termination without pickup.
A count of -2 executes the output module on call termination after pickup.
A count of -3 executes the output module on line busy termination.

Default: output module called as soon as CID received

--verbose <0-9> | -v <0-9>

Verbose mode.  Verbose mode. Sends information to the client logfile and displays information for the -D  option.  Set a higher number for more information.  Verbose mode 0 turns of logging.

Default: Verbose 1

--version | -V

Display version and exit.

--wakeup | -W

Works only on X-Windows and Gnome. On the first ring, this causes module ncid-wakeup to be executed to wake the monitor and/or exit the screensaver. Do not use with the "--module | -m" option.



Set the port number.

Default: 3333


Set the HOSTNAME or IP_Address.

Default: (localhost)




# Display the date as dd/mm/yyyy
ncid --alt-date

# run ncid in a terminal window, server on remote host
ncid --no-gui tardis.drwho.home

# only speak Caller ID
ncid --no-gui --module ncid-speak

# send CID output to GUI and desktop alert messages
ncid --module ncid-alert

# send CID output to a cell phone
ncid --no-gui --module ncid-page

# run ncid in a terminal window and tell the server to send the call log
ncid --no-gui --call-log

See Also

ncid.conf(5), ncid_modules(7), ncidd(8)

Referenced By

ncid-alert(1), ncid.conf(5), ncidd(8), ncid-initmodem(1), ncid-kpopup(1), ncid_modules(7), ncid-mysql(1), ncid-mysql-setup(8), ncid-mythtv(1), ncid-notify(1), ncidnumberinfo(1), ncid-page(1), ncid-samba(1), ncid-skel(1), ncid-speak(1), ncid-wakeup(1), ncid-yac(1), phonetz(1), update-cidcall(1).

2023-6-24 NCID