@tinyideas/contitest-cli

CLI tool to scan and upload test plan snapshots

Installation

npm install -g @tinyideas/contitest-cli

Or use with npx (no installation required):

npx @tinyideas/contitest-cli scan
npx @tinyideas/contitest-cli push

Usage

1. Scan your project for test plan files

contitest scan

This will:

• Find all .test-plan.md files in your project
• Extract metadata (title, content preview, line count)
• Generate a snapshot in .contitest/data.json

2. Push the snapshot to the cloud

contitest push

This uploads your test plan snapshot to the contitest platform.

3. View on the dashboard

Visit the dashboard to see your test plan snapshots!

Configuration

The CLI automatically fetches its configuration from a remote JSON file hosted on Vercel. This allows the CLI to stay up-to-date without requiring new releases.

How It Works

1. Remote Config (Default): The CLI fetches https://contitest.tinyideas.dev/cli-config.json which contains:

   {
     "convexUrl": "https://charming-firefly-443.convex.cloud",
     "minimumCliVersion": "0.1.0",
     "apiVersion": "v1",
     "updatedAt": "2025-01-24T00:00:00Z"
   }

2. Priority Order: The CLI resolves the Convex URL in this order:

   • --url flag (explicit override)
   • .env.local file (VITE_CONVEX_URL or CONVEX_URL)
   • process.env (VITE_CONVEX_URL or CONVEX_URL)
   • Remote config (fetched from Vercel)

3. Caching: Config is cached for 5 minutes to reduce network requests.

Override for Local Testing

To test with a local config server:

export CONTITEST_CONFIG_URL=http://localhost:3000/cli-config.json
export CONTITEST_ALLOW_UNPINNED_CONFIG=1
export CONTITEST_ALLOW_INSECURE_HTTP=1
contitest scan --verbose

See cli/LOCAL_TESTING.md for detailed local testing instructions.

Config File Location

The config file is served from the main app's public/cli-config.json folder and deployed to Vercel alongside the application. To update the Convex URL:

1. Edit public/cli-config.json in the main repository
2. Commit and push
3. Vercel automatically deploys the update
4. CLI picks up changes after cache expires (5 minutes)

Security notes

• Remote config is fetched over HTTPS from the pinned host contitest.tinyideas.dev only when pushing data. To use a different host, set CONTITEST_ALLOW_UNPINNED_CONFIG=1 and CONTITEST_CONFIG_URL=https://your-host/cli-config.json and ensure you trust it.
• Authentication tokens are stored at ~/.contitest/auth.json with restrictive permissions (0700 dir / 0600 file). On shared machines, prefer OS keychain storage or rotate tokens frequently.
• Provide Convex URLs over HTTPS; set --url or CONVEX_URL/VITE_CONVEX_URL. HTTP is blocked unless you opt into CONTITEST_ALLOW_INSECURE_HTTP=1 for local testing.

Options

scan

contitest scan [options]

Options:
  -d, --dir <directory>    Directory to scan (default: ".")
  --push                   Automatically push after scanning
  -u, --url <url>          Convex deployment URL (used with --push)
  --verbose                Show detailed parsing information
  --strict                 Fail on validation warnings

push

contitest push [options]

Options:
  -u, --url <url>        Convex deployment URL (overrides .env.local)

Example Workflow

# In your project directory
contitest scan
contitest push

# Or scan and push in one command
contitest scan --push

# Done! View your snapshots on the dashboard

License

MIT