CLI Reference

Edge Connector Reference

The Edge Connector CLI (edge-connector) provides commands to authenticate, generate tool implementations, manage bundles, test locally, package, upload, and manage cloud connectors.

edge-connector [command] [options]

Global options:

Option	Description
`--version`	Print the CLI version
`--auto-resume`	Auto-resume from previous running state. Used by autostart to restore the connector to its last known state after a system reboot.
`--help`	Display help for any command

Running edge-connector with no arguments launches a guided interactive menu. The menu walks you through the most common workflows in order:

Authenticate — log in via browser or token
Generate — scaffold tool implementations from the registry
Upload — package and upload your tools as a bundle
Bundle management — list, checkout, assign, and rename bundles
Cloud operations — provision, start, stop, and manage cloud connectors

Each top-level command also supports an --interactive flag (or -i where it does not conflict with other short flags) to launch its own guided prompts instead of requiring all options on the command line.

# Launch the full interactive menu
edge-connector

# Launch interactive mode for a specific command
edge-connector auth --interactive
edge-connector generate --interactive
edge-connector run --interactive

`auth`

Authenticate the Edge Connector with the nara platform. After successful authentication, the CLI syncs the default bundle for your organization.

edge-connector auth [options]

Options:

Option	Description
`-t, --token <token>`	Authentication token — accepts a JWT string or a path to a JSON file containing a `token` field
`-b, --browser`	Authenticate via browser OAuth flow (opens your default browser)
`-i, --interactive`	Launch interactive authentication prompts

Behavior:

When --token is provided, the CLI validates the JWT (checks expiry and organization membership), saves it to the configured token path, and syncs the default bundle.
When --browser is provided, the CLI starts the desktop OAuth flow: it opens a browser window, waits for authorization, and saves the returned token.
When no options are provided (or --interactive is used), the CLI launches an interactive prompt that guides you through authentication.
--token and --browser cannot be used together.

Examples:

# Authenticate via browser
edge-connector auth --browser

# Authenticate with a JWT string
edge-connector auth --token "eyJhbGciOiJSUzI1NiIs..."

# Authenticate with a token file
edge-connector auth --token ./my-token.json

# Interactive mode
edge-connector auth --interactive

`run`

Start the Edge Connector locally for testing custom tool implementations. This command launches the runtime in test mode with state persistence and autostart disabled.

edge-connector run [options]

Options:

Option	Default	Description
`-i, --implementations <path>`	`./custom-implementations`	Path to your custom implementations directory
`-T, --type <type>`	`EDGE`	Connector type
`-u, --url <url>`	`ws://localhost:3001`	Platform server WebSocket URL
`--interactive`		Run in interactive mode with guided prompts

Behavior:

Sets the following environment variables on the spawned process:
- EC_TEST_RUN=1 — enables test mode
- EC_DISABLE_STATE=1 — disables state file persistence
- EC_DISABLE_AUTOSTART=1 — prevents autostart registration
Spawns the Edge Connector runtime as a child process with the specified configuration. The runtime’s stdout and stderr are piped to your terminal.
The runtime connects to the nara platform server, loads your custom implementations, and begins accepting tool execution requests.
Press Ctrl+C to stop the test run.

Examples:

# Run with default settings (local development)
edge-connector run

# Run with a custom implementations path and production server
edge-connector run -i ./my-tools -u wss://tool-rpc.nara.de

# Interactive mode
edge-connector run --interactive

`bundle`

Manage tool bundles for your organization. Bundles are versioned collections of tool implementations that are uploaded to the platform and distributed to Edge Connector instances.

edge-connector bundle <subcommand> [options]

`bundle list`

List all bundles registered for your organization.

edge-connector bundle list [--api <url>]

Displays each bundle with its name (or short ID), version, tool count, total size, and whether it is the organization default. The currently checked-out bundle is marked with an asterisk (*).

`bundle checkout`

Switch to a different bundle or detach from the current bundle.

edge-connector bundle checkout <bundleId> [--api <url>]
edge-connector bundle checkout --new

Option	Description
`<bundleId>`	Full or partial bundle ID to switch to
`--new`	Detach from current bundle; the next upload creates a new bundle

When you check out a bundle, the CLI syncs tool references to your local tools/ directory. For each tool in the bundle, if you have local source code, it is preserved. If not, a .ref.json reference file is created.

`bundle status`

Compare your local tools against the currently checked-out bundle.

edge-connector bundle status [--api <url>]

Shows each tool with a status indicator:

[src] — local source file exists
[ref] — using a server-hosted reference
+ — new tool that will be added on next upload
- — tool missing locally that will be removed on next upload

`bundle tools`

List all available tool versions for your organization across all bundles.

edge-connector bundle tools [--api <url>]

Shows each tool name, its latest version number, and the total number of available versions.

`bundle ref`

Fetch a tool version reference pointer (.ref.json) for a specific tool.

edge-connector bundle ref <toolName> [--version <n>] [--api <url>]

Option	Description
`<toolName>`	Name of the tool to reference
`--version <n>`	Pin to a specific version number (defaults to latest)

Creates a .ref.json file in the tools/ directory that points to the specified tool version on the server. When the bundle is uploaded, the platform resolves this reference to the correct compiled implementation. A local source file for the same tool must not exist — remove it first to use a reference.

`bundle set-default`

Set a bundle as the organization default. New Edge Connector instances that do not have a specific bundle assignment will automatically sync this bundle.

edge-connector bundle set-default <bundleId> [--api <url>]

`bundle assign`

Assign a bundle to a specific deployment. The assigned Edge Connector instance will sync this bundle on its next check.

edge-connector bundle assign <bundleId> --deployment <deploymentId> [--version <n>] [--api <url>]

Option	Description
`--deployment <deploymentId>`	(Required) Deployment ID to assign the bundle to
`--version <n>`	Pin to a specific bundle version (defaults to latest)

`bundle rename`

Rename a bundle to give it a human-readable label.

edge-connector bundle rename <bundleId> <name> [--api <url>]

`cloud`

Manage the lifecycle of a cloud connector for your organization. Cloud connectors are fully managed Edge Connector instances running on nara’s cloud infrastructure.

edge-connector cloud <subcommand>

`cloud provision`

Provision a new cloud connector record for your organization.

edge-connector cloud provision [--env <env>]

Option	Default	Description
`--env <env>`	`prod`	Target environment: `dev`, `stage`, or `prod`

`cloud start`

Start the cloud connector runtime. The platform spins up the Kubernetes resources and begins running your assigned bundle.

edge-connector cloud start

`cloud stop`

Stop the cloud connector runtime. Resources are scaled down but the deployment record is preserved.

edge-connector cloud stop

`cloud status`

Retrieve the current status of your cloud connector, including runtime state, desired state, environment, image tag, and the latest operation.

edge-connector cloud status

`cloud force-complete`

Force-complete a stuck cloud operation. Use this if a provision, start, or stop operation is not progressing.

edge-connector cloud force-complete

`cloud delete`

Delete the cloud connector and tear down all associated Kubernetes resources. This action is irreversible.

edge-connector cloud delete

`generate`

Generate boilerplate code for a tool implementation. Connects to the nara platform server to fetch the tool’s parameter and result schemas, then generates a TypeScript file with the correct types and a handler stub.

edge-connector generate [options]

Alias: g

Options:

Option	Default	Description
`-l, --language <language>`		Target language (`typescript`)
`-t, --tool <tool>`		Name of the EDGE tool to generate
`-o, --output <path>`	`./custom-implementations`	Output directory for generated files
`-i, --interactive`		Launch interactive prompts for tool selection

Behavior:

Connects to the nara platform server using your saved authentication token.
Fetches the list of EDGE tools available to your organization (excluding built-in diagnostic tools).
Generates a TypeScript implementation file for the specified tool, including typed parameters, result schema, and error handling scaffolding.
If --language or --tool is omitted, the CLI falls back to interactive mode.

Examples:

# Generate a specific tool
edge-connector generate -l typescript -t getSystemInfo -o ./custom-implementations

# Same command using the short alias "g"
edge-connector g -l typescript -t getSystemInfo

# Interactive mode -- browse and select tools
edge-connector g --interactive

`upload`

Package your custom implementations and upload them to the nara platform as a bundle. This command combines the package and upload steps into a single operation.

edge-connector upload [options]

Options:

Option	Default	Description
`-f, --file <path>`		Path to a pre-built `.tgz` bundle file (skips packaging)
`-i, --implementations <path>`	`./custom-implementations`	Path to implementations directory
`--no-build`		Skip TypeScript compilation before packaging
`--api <url>`	Platform API URL from config	Platform API base URL
`--name <text>`		Optional human-readable name for the bundle
`--notes <text>`	`Uploaded via CLI`	Notes about this bundle version

Behavior:

If --file is not provided, the CLI first runs the package step: compiles TypeScript tool files with esbuild, creates a manifest, and produces a .tgz archive.
The archive is uploaded to the platform.
Maximum bundle size is 50 MB.
If you are currently tracking a bundle (currentBundleId in config), the upload updates that bundle with a new version. Otherwise, a new bundle is created.
Manifest references (.ref.json) are automatically extracted from the .tgz archive, allowing you to compose bundles from both local and server-hosted tools.
On success, the CLI prints the new bundle version number.

Examples:

# Package and upload in one step
edge-connector upload

# Upload a pre-built bundle
edge-connector upload -f ./artifacts/edge-bundle-org123-1710000000.tgz

# Upload with a name and notes
edge-connector upload --name "Production v2" --notes "Added VPN diagnostic tool"

`package`

Build a distributable bundle archive from your tool implementations without uploading. This is useful when you want to inspect the bundle before uploading or upload from a different machine.

edge-connector package [options]

Options:

Option	Default	Description
`-i, --implementations <path>`	`./custom-implementations`	Path to implementations directory
`-o, --out <dir>`	`./artifacts`	Output directory for the bundle archive
`--no-build`		Skip TypeScript compilation (assumes `dist/` already exists)

Behavior:

If node_modules/ does not exist in the implementations directory, pnpm install runs automatically before packaging.
Discovers tool source files in <implementations>/tools/ (.ts, .js, .mjs, .cjs).
TypeScript is auto-detected: if an index.ts file exists at the implementations root, it is treated as a TypeScript project and compiled accordingly.
Compiles each tool individually using esbuild into the dist/tools/ directory.
Generates an auto-index (dist/index.js) that re-exports all tool handlers from the compiled dist/tools/ files.
Discovers .ref.json reference files and includes them in the manifest.
Creates a .tgz archive containing the manifest and compiled output.
The archive file is named edge-bundle-<orgId>-<timestamp>.tgz.

Examples:

# Package with defaults
edge-connector package

# Package from a custom directory
edge-connector package -i ./my-tools -o ./build

# Package without rebuilding (use existing dist/)
edge-connector package --no-build

CLI Reference

Interactive menu

auth

run

bundle

bundle list

bundle checkout

bundle status

bundle tools

bundle ref

bundle set-default

bundle assign

bundle rename

cloud

cloud provision

cloud start

cloud stop

cloud status

cloud force-complete

cloud delete

generate

upload

package

`auth`

`run`

`bundle`

`bundle list`

`bundle checkout`

`bundle status`

`bundle tools`

`bundle ref`

`bundle set-default`

`bundle assign`

`bundle rename`

`cloud`

`cloud provision`

`cloud start`

`cloud stop`

`cloud status`

`cloud force-complete`

`cloud delete`

`generate`

`upload`

`package`