Opcua CLI

php-opcua/opcua-cli — v4.4.0 skill

A pure-PHP, no-framework CLI tool for OPC UA. Wraps php-opcua/opcua-client into 11 composable single-shot commands. Every command supports --json for piping into jq / Unix tools, every connection method (auth, security, cert paths) is the same across commands, and the explore command opens a full-screen TUI for ad-hoc address-space browsing.

When to use this skill

Activate when the user wants to:

• Probe an OPC UA server from a shell (opcua-cli endpoints opc.tcp://server:4840)
• Read / write / watch process variables without writing PHP code
• Browse / explore the address space interactively (TUI) or scriptably (JSON)
• Generate typed PHP classes from a vendor's NodeSet2.xml (generate:nodeset)
• Export a server's address space to NodeSet2.xml (dump:nodeset)
• Set up CI integration tests that read a known node and assert a value
• Manage the per-user trust store (trust, trust:list, trust:remove)
• Pipe OPC UA data into jq, awk, Telegraf, monitoring scripts

Do NOT activate for: building a long-running OPC UA service (use opcua-client or opcua-session-manager directly), library-level integration (use opcua-client), or framework-bound integration (use laravel-opcua / symfony-opcua).

The 60-second mental model

$ opcua-cli <command> <endpoint> [<nodeId> | <args>] [--security-policy=...] [--username=...] [--json] [--debug-*]
                │
                ▼
        Application (src/Application.php) — registers 11 commands, parses argv via ArgvParser
                │
                ▼
        Command (one of 11 in src/Commands/) — implements CommandInterface
                │
                ▼
        CommandRunner (src/CommandRunner.php) — builds the Client (security, trust, timeout)
                │
                ▼
        php-opcua/opcua-client Client.connect() → service call → typed result
                │
                ▼
        OutputInterface (ConsoleOutput tree/text  |  JsonOutput machine-readable)
                │
                ▼
        stdout (data) | stderr (diagnostics) → caller's pipeline

Three things to know:

1. No framework. Not Symfony Console. Argument parsing is a custom ArgvParser, command dispatch is a custom CommandRunner. The only runtime dep beyond opcua-client is php-tui/php-tui (only loaded if you run explore).
2. Two output modes for every command: human-readable (ConsoleOutput, default — colored tree / table) and machine-readable (--json → JsonOutput). The JSON shape is stable and documented per-command; use it for scripts.
3. Stdout for data, stderr for diagnostics. --debug-stderr routes log lines to stderr so piping the data output through jq stays clean. The TUI command (explore) takes over the whole terminal and rejects --json / --debug (they'd corrupt the display).

Quick start (90% of use cases fit this shape)

# Probe — what does this endpoint speak?
opcua-cli endpoints opc.tcp://server.example:4840

# Read the canonical "is the server alive?" node
opcua-cli read opc.tcp://server.example:4840 'i=2259'         # Server.ServerStatus.State

# Read with JSON output → pipe to jq
opcua-cli read opc.tcp://server.example:4840 'ns=2;s=Temp' --json | jq -r '.value'

# Browse one level
opcua-cli browse opc.tcp://server.example:4840 'i=85'           # Objects folder

# Browse a tree, 3 levels deep
opcua-cli browse opc.tcp://server.example:4840 /Objects --recursive --depth=3

# Open the interactive TUI (Linux/macOS only)
opcua-cli explore opc.tcp://server.example:4840

# Write a value
opcua-cli write opc.tcp://server.example:4840 'ns=2;s=Setpoint' 42.5 --type=Double

# Watch a value change in real time
opcua-cli watch opc.tcp://server.example:4840 'ns=2;s=Temp'    # subscription mode (default)

When to load deeper references

The 11 commands

Security options (every connection-aware command)

Global options (every command)

v4.4.0 alignment

Lock-step with php-opcua/opcua-client v4.4.0. The CLI binds to the core directly — no service layer in between — so every server-facing command benefits transparently from the v4.4 additions:

• New aggregate / historyAggregate / historyInsert* / historyUpdate* / historyDelete* core methods are reachable from CLI flows that already touch history (but the CLI does NOT yet have first-class history / aggregate subcommands — would be a v4.5+ candidate)
• The HTTPS / Reverse Connect ext transports plug in via ClientBuilder::setTransport() — invisible to the CLI surface, just works against opc.https:// endpoints once those packages are installed alongside
• Pre-generated nodeset types (php-opcua/opcua-client-nodeset) are loaded transparently when present (CLI auto-discovers registrars via the autoloader)

Idiomatic patterns AI agents should follow

1. Always quote NodeId strings in shell — ns=2;s=Temp has a ; that bash treats as a command separator. Use single quotes: 'ns=2;s=Temp'.

2. -j / --json for any output you pipe to jq / awk / grep. Default human output has colors, padding, and tree-drawing characters that break parsing.

3. --debug-stderr instead of --debug when piping. --debug writes to stdout and corrupts JSON.

4. --type=<BuiltinType> on writes when you know the type — saves a read-before-write round trip. Without it, the CLI does an auto-detect read first.

5. Use the read command with --attribute=DataType to discover a node's type before writing. Cheap, no commit.

6. trust before connecting securely to a new server — opcua-cli trust opc.tcp://server:4840 pulls the cert into the user trust store, then subsequent commands honour --trust-policy. Without trust setup, --trust-policy=fingerprint connections to that server fail.

7. explore for ad-hoc, scripts for repeated operations. The TUI is great for "what does this server have?", terrible for automation. For automation use browse --recursive --depth=N --json and parse with jq.

8. --timeout=2 for fast-fail probes in CI. The default 5 seconds is fine interactively but stretches CI gates.

9. Don't use --password from a shell. Prefer reading from a file: --password="$(cat /run/secrets/opcua_pwd)" (or use a config file in php-opcua/laravel-opcua / symfony-opcua integrations).

10. Exit codes matter:

    • 0 — success
    • 1 — generic error (parse, validation, business logic)
    • 2 — connection error (DNS, TCP, TLS, OPC UA handshake)
    • 3 — authentication / security error
    • 4 — service-level OPC UA error (StatusCode != Good)

    Bash scripts can branch on these for selective retry.

Common pitfalls (read before generating code)

Don't write code that:

• Unquoted NodeIds in shell: ns=2;s=Temp — bash parses ; as a command separator
• --debug mixed with --json to stdout — debug lines corrupt the JSON output
• explore with --json or --debug — explicitly rejected (would corrupt the TUI)
• Hard-codes ~/.opcua as trust-store path — different per-user; use $HOME/.opcua or pass --trust-store=PATH explicitly
• dump:nodeset against a huge server without --namespace=N filter — the export can run for minutes and produce >100 MiB
• generate:nodeset writing into vendor/ — generated code belongs in your application's src/
• Loops calling opcua-cli read 100 times — each call pays the connect handshake (~150 ms). Use watch or a real PHP script via opcua-client.
• watch --interval=10 (polling every 10 ms) — hammers the server. Stick with subscription mode unless you have a reason.

Full catalog in references/PITFALLS.md.

Related packages in the php-opcua ecosystem

• opcua-client — the OPC UA client library this CLI wraps. v4.4+ required.
• opcua-client-nodeset — pre-generated types for 51 OPC Foundation companion specs. Auto-discovered by the CLI (no extra config) when installed in the project.
• opcua-session-manager — daemon for cross-request session persistence. Not used by opcua-cli (each command is one-shot — no benefit). Use it only from long-lived applications.
• laravel-opcua / symfony-opcua — framework integrations. The CLI is a separate utility; framework integrations replace it for in-app code, but the CLI stays useful for ops / debugging / generation.
• uanetstandard-test-suite — Docker-based OPC UA test servers. Useful target for trying every CLI command locally.

Distribution forms

The CLI ships in three forms (all from the same source):

• Composer dep: composer require php-opcua/opcua-cli → vendor/bin/opcua-cli
• Global composer install: composer global require php-opcua/opcua-cli → ~/.composer/vendor/bin/opcua-cli (add to PATH)
• PHAR / standalone binary: box.json.dist builds a single-file PHAR via bin/opcua-cli. Distributed via the GitHub Releases workflow (release-binaries.yml) — download a PHP-bundled binary for Linux / macOS / Windows.

Recommend vendor/bin for project-scoped use; global or PHAR for ops / CI-runner installs.