# ncs\_cli

`ncs_cli` - Frontend to the NSO CLI engine

## Synopsis

`ncs [options] [File]`

`ncs [--help] [--host Host] [--ip IpAddress | IpAddress/Port ] [--address Address] [--port PortNumber] [--cwd Directory] [--proto tcp> | ssh | console ] [--interactive] [--noninteractive] [--user Username] [--uid UidInt] [--groups Groups] [--gids GidList] [--gid Gid] [--opaque Opaque] [--noaaa]`

## Description

The ncs\_cli program is a C frontend to the NSO CLI engine. The `ncs_cli` program connects to NSO and basically passes data back and forth from the user to NSO.

ncs\_cli can be invoked from the command line. If so, no authentication is done. The archetypical usage of ncs\_cli is to use it as a login shell in /etc/passwd, in which case authentication is done by the login program.

## Options

`-h`; `--help`

> Display help text.

`-H`; `--host` \<HostName>

> Gives the name of the current host. The `ncs_cli` program will use the value of the system call `gethostbyname()` by default. The host name is used in the CLI prompt.

`-A`; `--address` \<Address>

> CLI address to connect to. The default is 127.0.0.1. This can be controlled by either this flag, or the UNIX environment variable `NCS_IPC_ADDR`. The `-A` flag takes precedence.

`-P`; `--port` \<PortNumber>

> CLI port to connect to. The default is the NSO IPC port, which is 4569 This can be controlled by either this flag, or the UNIX environment variable `NCS_IPC_PORT`. The `-P` flag takes precedence.

`-S`; `--socket-path` \<Path>

> Path of the UNIX domain socket to connect to, used in place of TCP (address and port). Controlled by either this flag, or the UNIX environment variable `NCS_IPC_PATH`. The `-S` flag takes precedence.

`-c`; `--cwd` \<Directory>

> The current working directory for the user once in the CLI. All file references from the CLI will be relative to the cwd. By default the value will be the actual cwd where ncs\_cli is invoked.

`-p`; `--proto` `ssh` | `tcp` | `console`

> The protocol the user is using to connect. This value is used in the audit logs. Defaults to "ssh" if `SSH_CONNECTION` environment variable is set, "console" otherwise.

`-i`; `--ip` \<IpAddress> | \<IpAddress/Port>

> The IP (or IP address and port) which NSO reports that the user is connecting from. This value is used in the audit logs. Defaults to the information in the `SSH_CONNECTION` environment variable if set, 127.0.0.1 otherwise.

`-v`; `--verbose`

> Produce additional output about the execution of the command, in particular during the initial handshake phase.

`-n`; `--interactive`

> Force the CLI to echo prompts and commands. Useful when `ncs_cli` auto-detects it is not running in a terminal, e.g. when executing as a script, reading input from a file or through a pipe.

`-N`; `--noninteractive`

> Force the CLI to only show the output of the commands executed. Do not output the prompt or echo the commands, much like a shell does for a shell script.

`-s`; `--stop-on-error`

> Force the CLI to terminate at the first error and use a non-zero exit code.

`-E`; `--escape-char` \<C>

> A special character that forcefully terminates the CLI when repeated three times in a row. Defaults to control underscore (Ctrl-\_).

`-J`; `-C`

> This flag sets the mode of the CLI. `-J` is Juniper style CLI, `-C` is Cisco XR style CLI.

`-u`; `--user` \<User>

> The username of the connecting user. Used for access control and group assignment in NSO (if the group mapping is kept in NSO). The default is to use the login name of the user.

`-g`; `--groups` \<GroupList>

> A comma-separated list of groups the connecting user is a member of. Used for access control by the AAA system in NSO to authorize data and command access. Defaults to the UNIX groups that the user belongs to, i.e. the same as the `groups` shell command returns.

`-U`; `--uid` \<Uid>

> The numeric user id the user shall have. Used for executing OS commands on behalf of the user, when checking file access permissions, and when creating files. Defaults to the effective user id (euid) in use for running the command. Note that NSO needs to run as root for this to work properly.

`-G`; `--gid` \<Gid>

> The numeric group id of the user shall have. Used for executing OS commands on behalf of the user, when checking file access permissions, and when creating files. Defaults to the effective group id (egid) in use for running the command. Note that NSO needs to run as root for this to work properly.

`-D`; `--gids` \<GidList>

> A comma-separated list of supplementary numeric group ids the user shall have. Used for executing OS commands on behalf of the user and when checking file access permissions. Defaults to the supplementary UNIX group ids in use for running the command. Note that NSO needs to run as root for this to work properly.

`-a`; `--noaaa`

> Completely disables all AAA checks for this CLI. This can be used as a disaster recovery mechanism if the AAA rules in NSO have somehow become corrupted.

`-O`; `--opaque` \<Opaque>

> Pass an opaque string to NSO. The string is not interpreted by NSO, only made available to application code. See "built-in variables" in [clispec(5)](/guides/nso-6.6/resources/man/clispec.5.md) and `maapi_get_user_session_opaque()` in [confd\_lib\_maapi(3)](/guides/nso-6.6/resources/man/confd_lib_maapi.3.md). The string can be given either via this flag, or via the UNIX environment variable `NCS_CLI_OPAQUE`. The `-O` flag takes precedence.

## Environment Variables

NCS\_IPC\_ADDR

> Which IP address to connect to.

NCS\_IPC\_PORT

> Which TCP port to connect to.

NCS\_IPC\_PATH

> Which UNIX domain socket to connect to, instead of TCP address and port.

NCS\_IPC\_ACCESS\_FILE

> Path to the file containing a secret if IPC access check is enabled.

SSH\_CONNECTION

> Set by openssh and used by *ncs\_cli* to determine client IP address etc.

TERM

> Passed on to terminal aware programs invoked by NSO.

## Exit Codes

0

> Normal exit

1

> Failed to read user data for initial handshake.

2

> Close timeout, client side closed, session inactive.

3

> Idle timeout triggered.

4

> Tcp level error detected on daemon side.

5

> Internal error occurred in daemon.

5

> User interrupted clistart using special escape char.

6

> User interrupted clistart using special escape char.

7

> Daemon abruptly closed socket.

8

> Stopped on error.

## Scripting

It is very easy to use `ncs_cli` from `/bin/sh` scripts. `ncs_cli` reads stdin and can then also be run in non interactive mode. This is the default if stdin is not a tty (as reported by `isatty()`)

Here is example of invoking `ncs_cli` from a shell script.

```
#!/bin/sh

ncs_cli << EOF
configure
set foo bar 13
set funky stuff 44
commit
exit no-confirm
exit
EOF
```

And here is en example capturing the output of `ncs_cli`:

```
#!/bin/sh
{ ncs_cli << EOF;
configure
set trap-manager t2 ip-address 10.0.0.1 port 162 snmp-version 2
commit
exit no-confirm
exit
EOF
} | grep 'Aborted:.*not unique.*'
if [ $? != 0 ]; then
  echo 'test2: commit did not fail'; exit 1;
fi
```

The above type of CLI scripting is a very efficient and easy way to test various aspects of the CLI.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nso-docs.cisco.com/guides/nso-6.6/resources/man/ncs_cli.1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.