CLI Reference

The cirata command-line tool provides terminal access to Cirata Symphony. It is used by operators and developers to authenticate, inspect the platform, manage extensions, interact with object storage, retrieve metrics, and invoke extension-provided services—all from a single binary with no external dependencies.

Obtaining the CLI

The CLI binary is included in every Symphony installation archive for Linux (AMD64), macOS (Apple Silicon), and Windows (AMD64). Contact the operator of your Symphony instance to obtain the binary for your platform. See the Command-Line Tool page for installation instructions.

Usage

cirata [OPTIONS] <command>

Running cirata with no arguments or with --help displays the list of available commands, including any dynamic commands discovered from connected extensions.

Global Options

Flag	Short	Description
--help	-h	Show help text for any command or subcommand
--config	-c	Path to a custom configuration file
--completion		Output shell completion script (auto-detects bash, zsh, fish, tcsh)
--insecure		Skip TLS certificate verification (for self-signed certificates)
--verbose	-v	Show warnings on stderr
--info	-vv	Show info-level messages on stderr
--debug	-vvv	Show debug-level messages on stderr

By default, the CLI only shows errors on stderr. Use the verbosity flags to see warnings (e.g., NATS TLS fallback) and diagnostic messages. During tab completion, all non-error output is suppressed regardless of flags.

Help is available at every level of the command hierarchy:

cirata --help                # top-level commands
cirata extension --help      # subcommands of extension
cirata object get --help     # usage for a specific subcommand

Shell Completion

Tab completion is available for Bash, Zsh, Fish, and tcsh. The --completion flag auto-detects the current shell and outputs the appropriate completion script. Add the relevant line to your shell startup file to enable it permanently:

Bash (~/.bashrc):

eval "$(cirata --completion)"

Zsh (~/.zshrc):

eval "$(cirata --completion)"

Fish (~/.config/fish/config.fish):

cirata --completion | source

tcsh (~/.tcshrc):

eval `cirata --completion`

When completion is active, pressing Tab will suggest available commands, subcommands, and flags—including dynamically discovered extension commands.

Authentication

The CLI must be authenticated before it can interact with a Symphony instance. Two authentication methods are supported:

Interactive Login

The login command initiates a browser-based authentication flow. It contacts the Symphony instance, discovers the OIDC configuration, and opens your default browser to authenticate with your organization's identity provider. After you log in, the CLI automatically creates an API key and stores it.

cirata login --address symphony.example.com

On success, the API key is stored in the OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service) and used automatically by subsequent commands.

If the OS keychain is not available (for example, in a headless SSH session or Docker container), the CLI falls back to storing the token in the configuration file and prints a warning. You can also request file storage explicitly:

cirata login --address symphony.example.com --insecure-storage

For headless environments where a browser is not available, you can supply a pre-created API key token directly:

cirata login --address symphony.example.com --token <token>

Token-Based Authentication

For scripts, CI/CD pipelines, and automated workflows, set the SYMPHONY_TOKEN environment variable instead of using interactive login:

export SYMPHONY_TOKEN="your-api-key-token"
cirata info

When SYMPHONY_TOKEN is set, the CLI uses it directly without reading the stored configuration or keychain.

Session Management

The logout command removes the stored token from both the OS keychain and the configuration file:

cirata logout

Configuration

The CLI stores its configuration in a TOML file at an XDG-compliant location:

Platform	Default Path
Linux	~/.config/cirata/symphony.toml
macOS	~/.config/cirata/symphony.toml
Windows	%APPDATA%\cirata\symphony.toml

Override the default with the CIRATA_CONFIG environment variable (sets the config file name) or the -c / --config flag (sets the full path).

The configuration file stores connection preferences. It is created automatically on first use. The API token is stored in the OS keychain by default—it only appears in this file when --insecure-storage was used or the keychain was unavailable.

Configuration Keys

Key	Type	Default	Description
client.token	string	—	API key token (only present when --insecure-storage was used or the OS keychain was unavailable)
client.nats_tls	boolean	true	Attempt TLS for native NATS connections. Set to false to skip TLS and suppress fallback warnings when connecting to a Symphony instance that does not have NATS TLS enabled.
client.tls_skip_verify	boolean	false	Skip TLS certificate verification for HTTPS connections. Use when connecting to a Symphony instance with a self-signed certificate. Equivalent to the --insecure flag.

Example ~/.config/cirata/symphony.toml:

[client]
  nats_tls = false

Commands

login

Authenticate with a Symphony instance.

cirata login [OPTIONS]

Flag	Short	Default	Description
--address	-a	symphony.cirata.com	Hostname of the Symphony instance (without https:// prefix)
--insecure-storage		false	Store the token in the plaintext config file instead of the OS keychain
--token	-t		Store a pre-created API key directly without the browser flow (for headless environments)

The command contacts the instance to retrieve its name and OIDC configuration, then opens your browser to authenticate with your organization's identity provider. After you log in, the CLI automatically creates an API key and stores it.

For headless environments where a browser is not available, use --token to supply a pre-created API key token directly. Create API key tokens in the Symphony UI under your account settings.

By default, the API key is stored in the OS keychain. Use --insecure-storage when running in environments without a keychain (headless servers, CI, Docker containers).

# Connect to the default instance
cirata login

# Connect to a named instance
cirata login -a symphony.internal.example.com

# Connect to an instance with a self-signed certificate
cirata login -a symphony.internal.example.com --insecure

logout

Remove the stored authentication token from the local configuration file. After logging out, commands that require authentication will fail until you log in again or set SYMPHONY_TOKEN.

cirata logout

credential

Manage stored credentials (CLI tokens and extension API keys).

cirata credential <subcommand>

credential list

List all stored credentials, showing the type (CLI or extension), name, storage location (keychain or file), and a token hint (last 4 characters).

cirata credential list

Output is a JSON array:

[
  {"type": "cli", "name": "api-token", "source": "keychain", "hint": "...xB4q"},
  {"type": "extension", "name": "ext-weather", "source": "file", "hint": "...mN2p"}
]

credential remove

Remove a specific stored credential by name.

# Remove an extension's stored token
cirata credential remove ext-weather

# Remove the CLI login token (equivalent to cirata logout)
cirata credential remove api-token

Output is JSON indicating whether the credential was found and removed:

{"removed": true, "name": "ext-weather"}

credential clear

Remove all stored credentials — both the CLI login token and all extension tokens.

cirata credential clear

Output is JSON indicating how many credentials were removed:

{"removed": 3}

info

Display information about the connected Symphony instance, including its name, version, and NATS connection address.

cirata info

account

Display information about the currently authenticated user account.

cirata account

version

Display the CLI version and build information.

cirata version

observability

Query metrics, logs, and traces collected by the Observability Extension. Commands appear dynamically when the extension is connected.

cirata observability find_all_namespaces
cirata observability find_metrics
cirata observability query_scalar_metrics http.requests.total

Requires an authenticated session. See Monitoring for details.

extension

Inspect extensions connected to the Symphony instance.

cirata extension <subcommand>

extension list

List all registered extensions and their connection status. The output includes each extension's name, address, and state. The features field is omitted for brevity.

cirata extension list

extension features

List all features exposed by connected extensions, including UI resources, routes, menus, widgets, storage buckets, and microservice endpoints.

cirata extension features

nats

Interact with the Symphony NATS messaging layer.

cirata nats <subcommand>

nats credentials

Obtain a NATS credential file for direct NATS connections. The output is a .creds file that can be used with nats-cli or any NATS client library.

cirata nats credentials > symphony.creds

# Then use with nats-cli
nats sub ">" --creds=symphony.creds

This is useful for debugging, monitoring message traffic, or building custom integrations that communicate with Symphony at the messaging layer.

object

Interact with Symphony object storage, which is backed by NATS JetStream Object Store. Objects are organised into named buckets.

cirata object <subcommand> [arguments]

object list

List all object store buckets, or list the objects within a specific bucket.

# List all buckets (shows name, size, replica count, TTL)
cirata object list

# List objects in a specific bucket (shows name, size, modification time)
cirata object list my-bucket

object get

Download an object from a bucket to a local file.

cirata object get <bucket-name> <object-name> [output-path]

Argument	Required	Description
bucket-name	Yes	Name of the object store bucket
object-name	Yes	Name of the object to retrieve
output-path	No	Local file path (defaults to the object name)

# Download to current directory using the object name
cirata object get config-bucket app.conf

# Download to a specific path
cirata object get config-bucket app.conf /tmp/app.conf

object put

Upload a local file to a bucket. The object name is derived from the file name.

cirata object put <bucket-name> <file-path>

cirata object put config-bucket ./app.conf

On success, prints a JSON summary with the object name, size, chunk count, digest, and modification time.

symphony

Server operation commands. These are used by the Symphony server itself during deployment and are not typically invoked directly by users.

cirata symphony <subcommand> [OPTIONS]

Subcommand	Description
run	Run the Symphony server directly
operate	Operate Symphony in a Kubernetes environment
backup	Produce a consistent archive of a running Symphony's state (requires symphony-admin)
restore	Restore a Symphony archive into a stopped Symphony's configuration directory

run and operate accept:

Flag	Short	Default	Description
--config	-c	/config	Configuration directory path

# Run directly (used by systemd on Linux)
cirata symphony run --config /var/lib/symphony

# Operate in Kubernetes (used by container entrypoint)
cirata symphony operate --config /config

backup

Calls POST /api/v1/admin/backup on a running Symphony and streams the response archive to a file or stdout. The server briefly disables JetStream, tars /config, and re-enables JetStream; the archive captures every Symphony-owned bucket, every user's private buckets, and the identity files in one operation. Requires the symphony-admin role on the authenticated user.

Flag	Short	Default	Description
--output	-o	Server-suggested filename in the current directory	Output path for the archive. - streams to stdout.
--pause-timeout		5m	Upper bound on the JetStream outage. Clamped to 30 s – 30 min server-side.
--progress		off	Print byte-count progress to stderr.

# Write to a file with a server-generated name.
cirata symphony backup

# Explicit path.
cirata symphony backup --output ./backup.tar

# Pipe to gzip or gpg.
cirata symphony backup -o - | gzip > backup.tar.gz

Backup is single-node only. In clustered NATS deployments the command refuses to run on a non-leader. Keycloak, when bundled in the Helm chart, has its own PVC and is not included.

restore

Extracts a backup archive into a stopped Symphony's /config directory. Runs entirely on the local filesystem; no authentication is required because the operator's shell access to /config is itself the authorisation.

On packaged installs the configuration directory is owned by a dedicated service user (RPM: /var/lib/symphony owned by symphony:symphony), and the restored tree must end up owned by that same user so the systemd unit can read its own files. Two equivalent ways to achieve that:

• Run as root (typical via sudo). Restore writes into the target as root and then propagates the target directory's ownership to every extracted entry. Convenient because it matches the surrounding sudo systemctl stop/start commands.
• Run as the service user directly (e.g. sudo -u symphony). Files are owned correctly at extraction time so the chown step is a no-op.

Flag	Short	Default	Description
--input	-i	Newest symphony-backup-*.tar in the current directory	Archive path. - reads from stdin.
--config-dir	-C	/config	Target configuration directory to restore into.
--force		off	Restore into a non-empty target. Existing contents are moved aside to .pre-restore-<timestamp>/ rather than deleted.
--skip-version-check		off	Accept archives whose Symphony version differs in major from this tool.
--override-hostname		off	Accept archives whose hostname differs from the current EXTERNAL_HOSTNAME. OIDC settings and JWT audience will need updating after restore.

# Restore the newest backup in the current directory into /var/lib/symphony
# (RPM/systemd install: run as root so it can write into the service
# user's state directory; restore chowns the extracted tree afterwards).
sudo cirata symphony restore --config-dir /var/lib/symphony

# Explicit path and target, overwriting an existing /config.
sudo cirata symphony restore --input ./backup.tar --config-dir /config --force

# Pipe an archive in from an encrypted source.
gpg --decrypt backup.tar.gpg | sudo cirata symphony restore -i - -C /config

Restoring into a populated /config requires --force. The existing contents are moved to .pre-restore-<timestamp>/ so the operation is reversible.

Restore performs three fix-ups automatically so archives can be restored into a different directory than the source was running in, and so packaged installs come up cleanly under their service user:

1. Rewrites absolute paths in nats.config (store_dir, logfile, account resolver dir) from the source's configuration directory to the target --config-dir. No manual edits needed when migrating between hosts or cluster layouts.
2. Creates log/, accounts/, and storage/ under the target directory if they are missing. log/ is excluded from the archive but NATS needs it at startup.
3. Chowns the restored tree to match the target directory's owner when invoked as root. Without this fix-up, a sudo cirata symphony restore would leave every file owned by root and the systemd unit (which drops to the service user) would fail its first read of nats.log with a permission error. The walk is a no-op when you run restore directly as the service user (files are already owned correctly), or when the target itself is root-owned.

See Backup and Recovery for the full restore procedure and verification steps.

Dynamic Extension Commands

One of the most powerful features of the CLI is dynamic command discovery. When extensions register NATS microservices with OpenAPI metadata, those services are automatically discovered and added to the CLI as top-level commands.

How It Works

1. The CLI connects to Symphony via NATS
2. It sends a PING to discover all registered microservices
3. For each service, it retrieves the OpenAPI specification from the service's metadata
4. Operations marked with the x-symphony-extension annotation in the OpenAPI spec are added as CLI subcommands

This means the CLI's command set grows automatically as extensions are added to the platform—no CLI updates are required.

Using Dynamic Commands

Dynamic commands appear as top-level commands named after the extension's service name:

cirata <service-name> <operation> [arguments]

Arguments are passed positionally, in the order defined by the extension's OpenAPI spec:

cirata datamigrator start-migration /source /target

Required parameters are indicated in the help text. If a required parameter is missing, the CLI prints an error.

Discovering Available Commands

Run cirata --help to see all commands, including dynamically discovered ones. Extension commands appear alongside the built-in commands:

cirata --help

You can also get help for a specific extension and its operations:

cirata datamigrator --help
cirata datamigrator start-migration --help

The help output for dynamic commands includes the NATS subject, parameter descriptions with types, and example invocations derived from the OpenAPI specification.

Discovery Behaviour

Dynamic command discovery requires a NATS connection. The CLI skips discovery for known built-in commands (login, logout, credential, info, account, version, extension, nats, object, symphony) to avoid unnecessary connection overhead. For unknown commands or when --help is used, discovery runs automatically with a 2-second timeout.

Environment Variables

Variable	Description
SYMPHONY_TOKEN	API key token for authentication (alternative to cirata login)
CIRATA_CONFIG	Override the default configuration file name (default: symphony)
CIRATA_NATS_TLS	Set to false to skip NATS TLS and suppress fallback warnings (overrides client.nats_tls in the config file)
CIRATA_TLS_SKIP_VERIFY	Set to true to skip TLS certificate verification for HTTPS connections (overrides client.tls_skip_verify in the config file)

Output Format

All commands produce JSON output, with one exception:

• nats credentials—NATS .creds file format

JSON output is pretty-printed with two-space indentation.

See Also

• Command-Line Tool—Obtaining and installing the CLI
• Account and Login—Creating API keys
• REST API—HTTP API reference
• Extensions—Building extensions with dynamic CLI commands