@11x.agency/n8n-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Robin Sadeghpour
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# n8n-agent-cli
+
+Lightweight CLI wrapper around the n8n REST API — built for AI agents.
+
+Fast, direct REST API calls for workflow management without MCP protocol overhead.
+
+## Install
+
+```bash
+npm install -g n8n-agent-cli
+```
+
+## Setup
+
+Get your API key from n8n: **Settings > API > Create API Key**
+
+```bash
+export N8N_BASE_URL="https://your-n8n-instance.com"
+export N8N_API_KEY="your-api-key"
+```
+
+Or pass via flags:
+```bash
+n8n-cli --url "https://..." --api-key "..." workflow list
+```
+
+## Commands
+
+```bash
+n8n-cli workflow list|get|create|update|delete|activate|deactivate|run
+n8n-cli execution list|get|retry|stop|delete
+n8n-cli variable list|get|set|delete
+n8n-cli tag list|create
+n8n-cli doctor                    # Check API connectivity
+```
+
+Use `--json` or `--quiet` for machine-readable output.
+
+## Claude Code Plugin
+
+Use this CLI with Claude Code via the [11x marketplace plugin](https://github.com/11x-agency/claude-marketplace/tree/main/plugins/n8n-agent-cli):
+
+```
+/plugin marketplace add 11x-agency/claude-marketplace
+/plugin install n8n-agent-cli@11x-marketplace
+```
+
+## Documentation
+
+Full documentation, examples, and contribution guidelines: [github.com/robinsadeghpour/n8n-cli](https://github.com/robinsadeghpour/n8n-cli)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { N8nApi, getConfig } from './lib/api.js';
+const program = new Command();
+program
+    .name('n8n-cli')
+    .description('Lightweight CLI for n8n API - designed for AI agents')
+    .option('--url <url>', 'n8n base URL', process.env.N8N_BASE_URL)
+    .option('--api-key <key>', 'n8n API key', process.env.N8N_API_KEY)
+    .option('--json', 'Output as JSON')
+    .option('-q, --quiet', 'Quiet mode - only output data');
+function output(data, options) {
+    if (options.json) {
+        console.log(JSON.stringify(data, null, 2));
+    }
+    else if (options.quiet) {
+        if (typeof data === 'object' && data !== null) {
+            console.log(JSON.stringify(data));
+        }
+        else {
+            console.log(data);
+        }
+    }
+    else {
+        console.log(JSON.stringify(data, null, 2));
+    }
+}
+function errorExit(msg, code = 1) {
+    console.error(msg);
+    process.exit(code);
+}
+// Doctor command
+program
+    .command('doctor')
+    .description('Check API connectivity')
+    .action(async () => {
+    try {
+        const opts = program.opts();
+        const baseUrl = opts.url || process.env.N8N_BASE_URL;
+        const apiKey = opts.apiKey || process.env.N8N_API_KEY;
+        if (!baseUrl || !apiKey) {
+            errorExit('Error: N8N_BASE_URL and N8N_API_KEY required');
+        }
+        const api = new N8nApi({ baseUrl, apiKey });
+        const info = await api.ping();
+        output({ status: 'ok', version: info.version }, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+// Workflow commands
+const workflow = program.command('workflow').description('Workflow management');
+workflow
+    .command('list')
+    .description('List all workflows')
+    .action(async () => {
+    try {
+        const api = new N8nApi(getConfig());
+        const { workflows } = await api.listWorkflows();
+        output(workflows, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+workflow
+    .command('get <id>')
+    .description('Get workflow by ID')
+    .action(async (id) => {
+    try {
+        const api = new N8nApi(getConfig());
+        const wf = await api.getWorkflow(id);
+        output(wf, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+workflow
+    .command('create <json>')
+    .description('Create workflow from JSON')
+    .action(async (json) => {
+    try {
+        const data = JSON.parse(json);
+        const api = new N8nApi(getConfig());
+        const wf = await api.createWorkflow(data);
+        output(wf, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+workflow
+    .command('update <id> <json>')
+    .description('Update workflow')
+    .action(async (id, json) => {
+    try {
+        const data = JSON.parse(json);
+        const api = new N8nApi(getConfig());
+        const wf = await api.updateWorkflow(id, data);
+        output(wf, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+workflow
+    .command('delete <id>')
+    .description('Delete workflow')
+    .action(async (id) => {
+    try {
+        const api = new N8nApi(getConfig());
+        await api.deleteWorkflow(id);
+        output({ success: true, id }, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+workflow
+    .command('activate <id>')
+    .description('Activate workflow')
+    .action(async (id) => {
+    try {
+        const api = new N8nApi(getConfig());
+        await api.activateWorkflow(id);
+        output({ success: true, id, active: true }, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+workflow
+    .command('deactivate <id>')
+    .description('Deactivate workflow')
+    .action(async (id) => {
+    try {
+        const api = new N8nApi(getConfig());
+        await api.deactivateWorkflow(id);
+        output({ success: true, id, active: false }, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+workflow
+    .command('run <id>')
+    .description('Trigger workflow manually')
+    .action(async (id) => {
+    try {
+        const api = new N8nApi(getConfig());
+        const result = await api.runWorkflow(id);
+        output({ success: true, executionId: result.executionId }, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+// Execution commands
+const execution = program.command('execution').description('Execution management');
+execution
+    .command('list')
+    .description('List executions')
+    .option('-l, --limit <number>', 'Limit results', '50')
+    .option('-s, --status <status>', 'Filter by status (running, success, error, waiting)')
+    .action(async (opts) => {
+    try {
+        const api = new N8nApi(getConfig());
+        const { data } = await api.listExecutions(parseInt(opts.limit), opts.status);
+        output(data, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+execution
+    .command('get <id>')
+    .description('Get execution by ID')
+    .action(async (id) => {
+    try {
+        const api = new N8nApi(getConfig());
+        const exec = await api.getExecution(id);
+        output(exec, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+execution
+    .command('retry <id>')
+    .description('Retry execution')
+    .action(async (id) => {
+    try {
+        const api = new N8nApi(getConfig());
+        await api.retryExecution(id);
+        output({ success: true, id }, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+execution
+    .command('stop <id>')
+    .description('Stop running execution')
+    .action(async (id) => {
+    try {
+        const api = new N8nApi(getConfig());
+        await api.stopExecution(id);
+        output({ success: true, id, stopped: true }, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+execution
+    .command('delete <id>')
+    .description('Delete execution')
+    .action(async (id) => {
+    try {
+        const api = new N8nApi(getConfig());
+        await api.deleteExecution(id);
+        output({ success: true, id }, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+// Variable commands
+const variable = program.command('variable').description('Variable management');
+variable
+    .command('list')
+    .description('List all variables')
+    .action(async () => {
+    try {
+        const api = new N8nApi(getConfig());
+        const { variables } = await api.listVariables();
+        output(variables, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+variable
+    .command('get <key>')
+    .description('Get variable')
+    .action(async (key) => {
+    try {
+        const api = new N8nApi(getConfig());
+        const v = await api.getVariable(key);
+        output(v, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+variable
+    .command('set <key> <value>')
+    .description('Set variable')
+    .action(async (key, value) => {
+    try {
+        const api = new N8nApi(getConfig());
+        const v = await api.setVariable(key, value);
+        output(v, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+variable
+    .command('delete <key>')
+    .description('Delete variable')
+    .action(async (key) => {
+    try {
+        const api = new N8nApi(getConfig());
+        await api.deleteVariable(key);
+        output({ success: true, key }, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+// Tag commands
+const tag = program.command('tag').description('Tag management');
+tag
+    .command('list')
+    .description('List all tags')
+    .action(async () => {
+    try {
+        const api = new N8nApi(getConfig());
+        const { tags } = await api.listTags();
+        output(tags, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+tag
+    .command('create <name>')
+    .description('Create tag')
+    .action(async (name) => {
+    try {
+        const api = new N8nApi(getConfig());
+        const t = await api.createTag(name);
+        output(t, program.opts());
+    }
+    catch (err) {
+        errorExit(`Error: ${err.message}`);
+    }
+});
+program.parse();

package/dist/lib/api.d.ts

@@ -0,0 +1,72 @@
+export interface N8nConfig {
+    baseUrl: string;
+    apiKey: string;
+}
+export interface Workflow {
+    id: string;
+    name: string;
+    active: boolean;
+    nodes: any[];
+    connections: any;
+    settings?: any;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Execution {
+    id: string;
+    workflowId: string;
+    mode: string;
+    status: string;
+    startedAt: string;
+    finishedAt?: string;
+    data?: any;
+    error?: string;
+}
+export interface Variable {
+    key: string;
+    value: string;
+}
+export interface Tag {
+    id: string;
+    name: string;
+    createdAt: string;
+}
+export declare class N8nApi {
+    private baseUrl;
+    private apiKey;
+    constructor(config: N8nConfig);
+    private request;
+    listWorkflows(): Promise<{
+        workflows: Workflow[];
+    }>;
+    getWorkflow(id: string): Promise<Workflow>;
+    createWorkflow(workflow: Partial<Workflow>): Promise<Workflow>;
+    updateWorkflow(id: string, workflow: Partial<Workflow>): Promise<Workflow>;
+    deleteWorkflow(id: string): Promise<void>;
+    activateWorkflow(id: string): Promise<void>;
+    deactivateWorkflow(id: string): Promise<void>;
+    runWorkflow(id: string): Promise<{
+        executionId: string;
+    }>;
+    listExecutions(limit?: number, status?: string): Promise<{
+        data: Execution[];
+    }>;
+    getExecution(id: string): Promise<Execution>;
+    retryExecution(id: string): Promise<void>;
+    stopExecution(id: string): Promise<void>;
+    deleteExecution(id: string): Promise<void>;
+    listVariables(): Promise<{
+        variables: Variable[];
+    }>;
+    getVariable(key: string): Promise<Variable>;
+    setVariable(key: string, value: string): Promise<Variable>;
+    deleteVariable(key: string): Promise<void>;
+    listTags(): Promise<{
+        tags: Tag[];
+    }>;
+    createTag(name: string): Promise<Tag>;
+    ping(): Promise<{
+        version: string;
+    }>;
+}
+export declare function getConfig(): N8nConfig;

package/dist/lib/api.js

@@ -0,0 +1,112 @@
+export class N8nApi {
+    baseUrl;
+    apiKey;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, '');
+        this.apiKey = config.apiKey;
+    }
+    async request(endpoint, options = {}) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                'X-N8N-API-KEY': this.apiKey,
+                'Content-Type': 'application/json',
+                ...options.headers,
+            },
+        });
+        if (!response.ok) {
+            const error = await response.text().catch(() => 'Unknown error');
+            throw new Error(`API Error ${response.status}: ${error}`);
+        }
+        return response.json();
+    }
+    // Workflows
+    async listWorkflows() {
+        return this.request('/workflows');
+    }
+    async getWorkflow(id) {
+        return this.request(`/workflows/${id}`);
+    }
+    async createWorkflow(workflow) {
+        return this.request('/workflows', {
+            method: 'POST',
+            body: JSON.stringify(workflow),
+        });
+    }
+    async updateWorkflow(id, workflow) {
+        return this.request(`/workflows/${id}`, {
+            method: 'PUT',
+            body: JSON.stringify(workflow),
+        });
+    }
+    async deleteWorkflow(id) {
+        await this.request(`/workflows/${id}`, { method: 'DELETE' });
+    }
+    async activateWorkflow(id) {
+        await this.request(`/workflows/${id}/activate`, { method: 'POST' });
+    }
+    async deactivateWorkflow(id) {
+        await this.request(`/workflows/${id}/deactivate`, { method: 'POST' });
+    }
+    async runWorkflow(id) {
+        return this.request(`/workflows/${id}/run`, { method: 'POST' });
+    }
+    // Executions
+    async listExecutions(limit = 50, status) {
+        let endpoint = `/executions?limit=${limit}`;
+        if (status)
+            endpoint += `&status=${status}`;
+        return this.request(endpoint);
+    }
+    async getExecution(id) {
+        return this.request(`/executions/${id}`);
+    }
+    async retryExecution(id) {
+        await this.request(`/executions/${id}/retry`, { method: 'POST' });
+    }
+    async stopExecution(id) {
+        await this.request(`/executions/${id}/stop`, { method: 'POST' });
+    }
+    async deleteExecution(id) {
+        await this.request(`/executions/${id}`, { method: 'DELETE' });
+    }
+    // Variables
+    async listVariables() {
+        return this.request('/variables');
+    }
+    async getVariable(key) {
+        return this.request(`/variables/${key}`);
+    }
+    async setVariable(key, value) {
+        return this.request('/variables', {
+            method: 'POST',
+            body: JSON.stringify({ key, value }),
+        });
+    }
+    async deleteVariable(key) {
+        await this.request(`/variables/${key}`, { method: 'DELETE' });
+    }
+    // Tags
+    async listTags() {
+        return this.request('/tags');
+    }
+    async createTag(name) {
+        return this.request('/tags', {
+            method: 'POST',
+            body: JSON.stringify({ name }),
+        });
+    }
+    // Health
+    async ping() {
+        return this.request('/');
+    }
+}
+export function getConfig() {
+    const baseUrl = process.env.N8N_BASE_URL || process.env.N8N_URL;
+    const apiKey = process.env.N8N_API_KEY;
+    if (!baseUrl || !apiKey) {
+        throw new Error('Missing N8N_BASE_URL or N8N_API_KEY');
+    }
+    return { baseUrl, apiKey };
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@11x.agency/n8n-cli",
+  "version": "1.0.0",
+  "description": "Lightweight CLI for n8n API - designed for AI agents",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "n8n-cli": "dist/index.js",
+    "n8n-agent-cli": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "n8n",
+    "cli",
+    "automation",
+    "ai",
+    "workflow",
+    "n8n-api"
+  ],
+  "license": "MIT",
+  "author": "Robin Sadeghpour",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/robinsadeghpour/n8n-cli.git"
+  },
+  "homepage": "https://github.com/robinsadeghpour/n8n-cli#readme",
+  "bugs": {
+    "url": "https://github.com/robinsadeghpour/n8n-cli/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3"
+  }
+}