Sync CLI Skill

skills/base44-cli/

Usage

1. CLI source folder path (required) - The local path to the Base44 CLI source code (must be a git repository)

How It Works

1. Reads the locally stored version from

   CLI_VERSION

   (e.g.,

   v0.0.17

   )
2. Compares against the CLI source repository to find changed command files
3. Only processes commands that have actually changed

Steps

Step 1: Gather Input

• CLI source folder path (e.g.,

  ~/projects/base44-cli

  or

  /Users/me/base44-cli

  )

Step 2: Validate Source Folder and Discover Structure

1. Check that the provided path exists and is a git repository (

   .git/

   directory exists)
2. Check for

   package.json

   with CLI-related content
3. Discover the commands directory - look for directories containing command files:
   • Common patterns:

     src/cli/commands/

     ,

     src/commands/

     ,

     commands/

     ,

     lib/commands/

   • Look for files with

     .command(

     or

     program.command

     patterns
4. Identify the CLI source root - the parent directory containing both commands and shared code

• <commands-path>

  : Path to commands directory (e.g.,

  src/cli/commands

  )

• <cli-root>

  : Path to CLI source root (e.g.,

  src/cli

  )

Step 3: Read Local Version and Detect Changes

1. Read the stored version from

   CLI_VERSION

   in the skills repository root (e.g.,

   v0.0.17

   )
2. Get changed command files using git in the CLI source folder:
   bash

   # From the CLI source folder, list command files changed since the stored version
   git diff --name-only <stored-version> HEAD -- <commands-path>

   If the stored version tag doesn't exist, fall back to:
   bash

   # List all command files if tag is missing
   git ls-files <commands-path>

3. Get infrastructure changes (CLI source root excluding commands):
   bash

   # From the CLI source folder, list infra files changed since the stored version
   git diff --name-only <stored-version> HEAD -- <cli-root> | grep -v "<commands-path>"

4. Present findings to the user before proceeding:

   Found X changed command files since vX.X.X:
   - <commands-path>/deploy.ts
   - <commands-path>/entities/push.ts
   - <commands-path>/auth/login.ts
   
   Found Y infrastructure changes (may affect all commands):
   - <cli-root>/utils/api-client.ts
   - <cli-root>/config/defaults.ts

5. If no changes detected (neither commands nor infra): Report "No changes since version X" and exit

Step 4: Check Infrastructure Changes

What to Look For

--verbose

--json

--help

package.json

How to Handle Infra Changes

1. Read each changed infra file to understand what changed
2. Identify cross-cutting impacts:
   • New global options → Update SKILL.md "Global Options" section
   • Changed defaults → Note in affected command references
   • Auth flow changes → Update auth-related references
   • New environment variables → Document in SKILL.md
   • API endpoint changes → May affect multiple commands
3. Flag for SKILL.md update if the change affects:
   • How users configure the CLI
   • Prerequisites or setup steps
   • Error messages users might see
   • Output format

Example Infrastructure Change

Changed file: (some config/defaults file)

Before:
  export const DEFAULT_TIMEOUT = 30000;
  
After:
  export const DEFAULT_TIMEOUT = 60000;

Impact: All commands now have 60s timeout instead of 30s
Action: Update SKILL.md "Configuration" or "Troubleshooting" section

Step 5: Process Each Changed Command

Step 5a: Route Command to the Correct Skill

logs

skills/base44-troubleshooter/

skills/base44-cli/

skills/base44-troubleshooter/

logs

monitor

status

health

skills/base44-cli/

create

deploy

entities push

login

references/

SKILL.md

Step 5b: Read Existing Skill Reference

references/

skills/base44-cli/                      <- project management commands
├── SKILL.md
└── references/
    ├── auth-login.md      <- for <commands-path>/auth/login.ts
    ├── auth-logout.md
    ├── auth-whoami.md
    ├── create.md          <- for <commands-path>/create.ts
    ├── deploy.md
    ├── entities-create.md <- for <commands-path>/entities/create.ts
    ├── entities-push.md
    ├── functions-create.md
    ├── functions-deploy.md
    ├── rls-examples.md
    └── site-deploy.md

skills/base44-troubleshooter/           <- troubleshooting commands
├── SKILL.md
└── references/
    └── project-logs.md    <- for <commands-path>/logs.ts (or similar)

<commands-path>/{parent}/{name}.ts

references/{parent}-{name}.md

Step 5c: Compare Source with Documentation

Extract from Source

• Command name and aliases
• Description/help text
• Available options and flags (name, alias, description, default, required, type)
• Usage examples (if present)
• Subcommands

Detect Changes

1. New commands (source exists, no reference file)
2. Changed command descriptions

-f

-F

create -n my-app

create my-app

create my-app

create -n my-app

• Named option:

  .option('-n, --name <value>', 'description')

  or

  .requiredOption(...)

• Positional argument:

  .argument('<name>', 'description')

  or in command definition

  .command('create <name>')

Document the Comparison

Command: deploy (<commands-path>/deploy.ts)

Source options:
  --force (-f): Force deployment [boolean, default: false]
  --env <name>: Target environment [string, required]

Documented options (references/deploy.md):
  --force (-f): Force deploy without confirmation [boolean, default: false]  
  --env <name>: Environment name [string, optional]

Changes detected:
  - --force: description changed
  - --env: required status changed (required vs optional)

Command: create (<commands-path>/create.ts)

Source (current):
  Positional: <name> - The app name [required]
  Options: --template (-t): Template to use [string, optional]

Documented (references/create.md):
  Options:
    -n, --name <name>: The app name [string, required]
    --template (-t): Template to use [string, optional]

Changes detected:
  - BREAKING: --name (-n) option converted to positional argument <name>
    Old syntax: npx base44 create -n my-app
    New syntax: npx base44 create my-app

Step 5d: Update Reference File

references/{command-name}.md

# base44 {command}

{Description from source}

## Syntax

```bash
npx base44 {command} [options]

Options

-o, --option <value>

Examples

{example usage from source}

Notes

### Step 6: Update Main Skill Files (if needed)

After processing all changed commands, update the SKILL.md of each affected skill:

**For `skills/base44-cli/SKILL.md`** (project management commands):
1. Update the **Available Commands** tables if commands were added/removed
2. Update **Quick Start** if workflow changed
3. Update **Common Workflows** sections if relevant

**For `skills/base44-troubleshooter/SKILL.md`** (troubleshooting commands):
1. Update the **Available Commands** table if troubleshooting commands were added/removed
2. Update the **Troubleshooting Flow** if command behavior changed

**General rules:**
- Keep the existing structure and formatting of each skill
- Do NOT change the frontmatter description unless explicitly asked

### Step 7: Update CLI_VERSION and Skill Frontmatter

After successfully updating all changed commands:

1. Get the current version/commit from the CLI source:
   ```bash
   # Get latest tag, or HEAD commit if no tags
   git describe --tags --always

1. Update

   CLI_VERSION

   in the skills repository root with the new version (e.g.,

   v0.0.47

   )
2. Update

   metadata.sourcePackage

   in

   skills/base44-cli/SKILL.md

   frontmatter. Set

   name

   to

   base44

   (the npm package being synced) and

   version

   to the new version without the

   v

   prefix (e.g.,

   0.0.47

   ). Example:
   yaml

   metadata:
     sourcePackage:
       name: base44
       version: 0.0.47

   This allows the Base44 CLI to detect when installed skills are out of date.

Step 8: Present Summary

## Sync Summary

### Version Updated
- Previous: v0.0.17
- Current: v0.0.20

### Changed Command Files Processed
- <commands-path>/deploy.ts
- <commands-path>/entities/push.ts

### Infrastructure Changes Reviewed
- (list infra files from git diff output)
- Example: config.ts (timeout increased to 60s)
- Example: api-client.ts (no user-facing changes)

### Files Updated
- references/deploy.md (updated options)
- references/entities-push.md (updated description)
- SKILL.md (updated command table, added timeout note)
- CLI_VERSION (v0.0.17 → v0.0.20)
- skills/base44-cli/SKILL.md frontmatter metadata.sourcePackage.version (0.0.17 → 0.0.20)

### Breaking Changes (highlight prominently)
- `create`: `-n, --name` option converted to positional argument
  - Old: `npx base44 create -n my-app`
  - New: `npx base44 create my-app`

### Option Changes
- `deploy --env`: now required (was optional)
- `entities push --dry-run`: default changed from true to false

### New Commands
- (none)

### Removed Commands  
- (none)

### Manual Review Recommended
- [List any changes that need verification]

Important Notes

• Git-based detection: This skill relies on git tags/commits to detect changes. Ensure the CLI source folder is a valid git repository.
• Preserve existing content: Don't remove detailed explanations, examples, or warnings unless they're outdated
• Keep formatting consistent: Match the existing style of SKILL.md and reference files
• Maintain progressive disclosure: Keep detailed docs in references, summaries in SKILL.md
• Flag uncertainties: If source code is unclear, flag it for manual review
• Respect RLS/FLS docs: The

  entities-create.md

  and

  rls-examples.md

  contain hand-written security documentation - update carefully

Troubleshooting

git tag -l

.command(

program.command

.option(

.argument(

<argName>

.command('cmd <argName>')

description:

.description(

entities push

entities/push.ts

CLI_VERSION