symb-ai-prompts

Interactive CLI to save AI prompts into a central git repository, organized by project (derived from the git remote or folder name of the app you run it from). It can stage, commit, and push updates to the central library when you finish a session.

npm package: symb-ai-prompts on npm

Requirements

| Requirement | Notes | |-------------|--------| | Node.js | 18+ (see engines in package.json) | | Git | Installed and on PATH (git used for clone, detect project, push) | | Terminal | A real interactive terminal (TTY). The CLI will exit if stdin/stdout are not a TTY (e.g. some IDE “Run” panels, pipes, CI without a pseudo-TTY). | | Central repo access | The central prompt library is a private Bitbucket repo by default. You need SSH access (recommended) or configure HTTPS + credentials via SYMB_AI_PROMPTS_REMOTE. |

Install

Option A — Global (recommended for daily use)

npm install -g symb-ai-prompts

After this, the commands symb-ai-prompts and symb-save-prompt are on your PATH (if your Node/npm global bin directory is on PATH — common with nvm after a normal shell startup).

Option B — Per project (no global install)

From your application repository root:

npm install symb-ai-prompts --save-dev

The symb-ai-prompts binary is installed under node_modules/.bin/. It is not on your shell PATH unless you use npx or an npm script (see below).

Option C — Run without installing (one-off)

npx symb-ai-prompts@latest

Useful to try the latest published version from any directory (still needs TTY and central repo resolution as below).

How to run

If you installed globally

1. Open a normal terminal (Terminal.app, iTerm, VS Code / Cursor integrated terminal).

2. Change directory to the app project where you want prompts attributed (the tool reads git here, especially origin):

   cd /path/to/your-application-repo

3. Start the CLI:

   symb-ai-prompts

   Equivalent alias:

   symb-save-prompt

4. Follow the interactive prompts (choose file, append/create, body input mode, etc.). When the flow completes, it may commit and push the central library according to the tool’s git steps.

If you installed locally (npm i symb-ai-prompts without -g)

From the same directory as that project’s package.json:

npx symb-ai-prompts

Or add a script to package.json:

{
  "scripts": {
    "save-prompt": "symb-ai-prompts"
  }
}

Then:

npm run save-prompt

Why symb-ai-prompts alone might “do nothing” or fail: a local install does not put the command on your global PATH. Use npx symb-ai-prompts, npm run …, or install globally with -g.

Central prompt repository (where markdown is stored)

The CLI needs a git clone of the central library (the repo that contains prompts/by-project/...).

Default behavior (published package, first run)

If you do not set SYMB_AI_PROMPTS_ROOT or a config file with centralRepo, the tool will clone the default remote into:

• macOS / Linux: ~/.config/symb-ai-prompts/central
• Windows: under your user profile, same relative path under .config as implemented by Node’s os.homedir()

Requirements:

• Network on first run.
• Permission to clone the remote (SSH key to Bitbucket, or override remote — see environment variables).

Later runs will try git pull in that folder when possible; if offline or pull fails, the last successful clone is still used.

Override: config file (recommended for custom paths)

Create a JSON file (first match wins; see full list in source lib/config.js):

User default (macOS / Linux):

~/.config/symb-ai-prompts/config.json

{
  "centralRepo": "/absolute/path/to/your/central-clone"
}

Windows (example): %USERPROFILE%\.config\symb-ai-prompts\config.json with the same shape.

Enterprise / IT: optional machine-wide paths such as /Library/Application Support/symb-ai-prompts/config.json (macOS) or /etc/symb-ai-prompts/config.json (Linux) — same JSON shape.

Override: environment variables

| Variable | Purpose | |----------|---------| | SYMB_AI_PROMPTS_ROOT | Absolute path to an existing central git clone (highest priority). | | SYMB_AI_PROMPTS_CONFIG_FILE | Path to a single config.json file containing centralRepo. | | SYMB_AI_PROMPTS_REMOTE | Git remote URL used for auto-clone when no central path is configured (HTTPS with token manager, or SSH URL). | | SYMB_AI_PROMPTS_NO_AUTO_CLONE | Set to 1 to disable auto-clone; you must then set centralRepo via config or SYMB_AI_PROMPTS_ROOT. |

Develop from a clone of this repo

If you run the CLI from a full checkout of symb-ai-prompts that contains both .git and prompts/by-project, that checkout is used as the central library without extra config (developer convenience).

Troubleshooting

| Symptom | What to try | |---------|-------------| | command not found: symb-ai-prompts | Use npm i -g symb-ai-prompts, or npx symb-ai-prompts from a project where the package is installed, or fix PATH so your global npm bin directory is included (nvm: source ~/.nvm/nvm.sh). | | “requires a TTY” / exits immediately | Run in a normal interactive terminal, not a non-TTY runner. | | Clone / access errors | Ensure Bitbucket SSH (or set SYMB_AI_PROMPTS_REMOTE to an HTTPS URL your machine can authenticate to). For private repos there is no way to avoid some credential mechanism. | | “Could not resolve central prompt repository” | Set ~/.config/symb-ai-prompts/config.json with centralRepo, or SYMB_AI_PROMPTS_ROOT, or allow auto-clone (remove SYMB_AI_PROMPTS_NO_AUTO_CLONE if set). |

npm registry link

• Package page: https://www.npmjs.com/package/symb-ai-prompts

Install examples from the registry:

npm install -g symb-ai-prompts@latest
npm install symb-ai-prompts@latest --save-dev
npx symb-ai-prompts@latest

License

ISC (see package.json).