Nexical CLI

The Nexical CLI is the official command-line interface for the Nexical Orchestrator. It allows developers, platform engineers, and administrators to interact with the Nexical API directly from their terminal.

Whether you are managing teams, configuring projects, triggering jobs, or handling authentication tokens, the CLI provides a robust and scriptable interface for all your orchestration needs.

🚀 Getting Started

Prerequisites

• Node.js: v22 or higher
• NPM: v10 or higher

Installation

Install the package from NPM package repository:

npm install -g @nexical/cli

Local Development

To run the CLI locally during development, you can use npm start. To pass arguments to the CLI, use the -- separator:

# Example: Running the 'whoami' command
npm start -- whoami

# Example: Logging in
npm start -- login

Alternatively, you can link the binary globally to use the nexical command directly:

npm link
nexical --help

🔑 Authentication

The CLI supports a secure Device Flow for authentication, making it easy to log in from your terminal without handling sensitive passwords directly.

1. Log In

Start the authentication process. This will provide a verification URL and a code.

nexical login

Follow the on-screen instructions to authorize the device via your browser.

2. Verify Session

Check your current logged-in status and user details.

nexical whoami

🛠️ Usage & Commands

The CLI is structured into resource-based commands. You can always run nexical <command> --help to see available subcommands and options.

👥 Teams (team)

Manage user teams and memberships.

| Command | Usage | Description | | :--- | :--- | :--- | | list | nexical team list | List all teams you belong to or own. | | create | nexical team create <name> [--slug <slug>] | Create a new team. | | get | nexical team get <teamId> | View details of a specific team. | | update | nexical team update <teamId> [--name <n>] [--slug <s>] | Update team settings. | | invite | nexical team invite <teamId> <email> [--role <role>] | Invite a user to a team. | | delete | nexical team delete <teamId> [--confirm] | Delete a team permanently. |

📂 Projects (project)

Manage projects within your teams.

| Command | Usage | Description | | :--- | :--- | :--- | | list | nexical project list <teamId> | List all projects in a team. | | create | nexical project create <teamId> <name> [--repo <url>] | Create a new project. | | get | nexical project get <teamId> <projectId> | Get project details. | | update | nexical project update <teamId> <projectId> ... | Update project configuration. | | delete | nexical project delete <teamId> <projectId> | Delete a project. |

🌿 Branches (branch)

Manage development branches for your projects.

| Command | Usage | Description | | :--- | :--- | :--- | | list | nexical branch list <teamId> <projectId> | List branches. | | create | nexical branch create <teamId> <projectId> <name> | Create a branch. | | get | nexical branch get <teamId> <projectId> <branchId> | Get branch details. | | delete | nexical branch delete ... | Delete a branch. |

⚙️ Jobs (job)

Trigger and monitor orchestration jobs.

| Command | Usage | Description | | :--- | :--- | :--- | | list | nexical job list <teamId> <projectId> <branchId> | List recent jobs. | | trigger| nexical job trigger ... <type> [--input <json>] | Trigger a new job (e.g., deploy). | | get | nexical job get ... <jobId> | Get job details. | | logs | nexical job logs ... <jobId> | Stream or view logs for a job. |

🎟️ API Tokens (token)

Manage personal access tokens for scripting and CI/CD.

| Command | Usage | Description | | :--- | :--- | :--- | | list | nexical token list | List your active tokens. | | create | nexical token create <name> [--scopes <list>] | Generate a new API token. | | revoke | nexical token revoke <id> | Revoke a token. |

🛡️ Admin (admin)

System administration commands (requires elevated permissions).

| Command | Usage | Description | | :--- | :--- | :--- | | create-user | nexical admin create-user <name> <email> <password> | Create a system user. |

🏗️ Project Structure

The codebase is organized to be modular and extensible:

src/
├── commands/           # Command implementations
│   ├── team/           # Team-related commands
│   ├── project/        # Project-related commands
│   └── ...
├── utils/              # Shared utilities (API client, config)
└── index.ts            # CLI entry point

Each command is a class extending BaseCommand from @nexical/cli-core, enforcing a consistent structure for arguments, help text, and error handling.

🧪 Testing

We use Vitest for testing.

# Run unit tests
npm run test:unit

🤝 Contributing

1. Fork the repository.
2. Clone your fork.
3. Install dependencies (npm install).
4. Creating a Command:
   • Add a new file in src/commands/<topic>/<verb>.ts.
   • Extend BaseCommand.
   • Define static description and static args.
   • Implement run().
5. Test your changes.
6. Submit a Pull Request.

License

Apache-2.0