@notis_ai/cli 0.2.0-beta.35.1 → 0.2.0-beta.41.1

package/skills/notis-cli/SKILL.md

@@ -22,18 +22,13 @@ Activate this skill when:
 - the user wants to use an integration-backed capability through Notis rather than a first-class local tool
 - the task mentions the `notis` CLI directly
 
-In a **Vercel Sandbox** or hosted shell environment, use the registry-resolved published npm package:
+Use the registry-resolved published npm package everywhere:
 
-- `npm exec --yes --package @notis_ai/cli@latest -- notis ...`
+- `npx --package @notis_ai/cli@latest -- notis ...`
 
-Do not rely on a globally installed `notis` binary in a sandbox. It may come from an older snapshot. The CLI is pre-authenticated through `NOTIS_JWT`, so this registry-resolved command works without local login state.
+Always use this NPX command form so the agent runs the current published CLI. In hosted shells, the CLI is pre-authenticated through `NOTIS_JWT`; locally, Notis Desktop keeps the CLI auth profile current for NPX invocations.
 
-In a **local repo workspace**, prefer the repo-local CLI entrypoint:
-
-- from the repo root: `node packages/cli/bin/notis.js ...`
-- from app workspaces under `.context/`: `node ../../packages/cli/bin/notis.js ...`
-
-The Notis desktop app automatically installs and keeps this `notis-cli` skill updated alongside the `notis-apps` skill for local agents. No separate manual skill install is needed on desktop.
+Notis Desktop keeps the CLI auth profile current for NPX runs. This `notis-cli` skill is delivered through normal Notis skill sync for the signed-in user, alongside other curated skills.
 
 ## Critical rule for missing tools
 
@@ -61,47 +56,47 @@ Important: `deploy` means updating the installed app artifact for the current us
 ### App development workflow
 
 1. Scaffold a new app:
-   - `node packages/cli/bin/notis.js apps init`
+   - `npx --package @notis_ai/cli@latest -- notis apps init`
 2. Or pull an existing app's source to edit it locally (the project is linked automatically):
-   - `node packages/cli/bin/notis.js apps pull <app-id>`
-   - then run `npm install`, `node packages/cli/bin/notis.js apps dev`, edit, build, and deploy
+   - `npx --package @notis_ai/cli@latest -- notis apps pull <app-id>`
+   - then run `npm install`, `npx --package @notis_ai/cli@latest -- notis apps dev`, edit, build, and deploy
 3. Develop locally with live reload:
-   - `node packages/cli/bin/notis.js apps dev`
+   - `npx --package @notis_ai/cli@latest -- notis apps dev`
 4. Build the production artifact:
-   - `node packages/cli/bin/notis.js apps build`
+   - `npx --package @notis_ai/cli@latest -- notis apps build`
 5. Verify the built artifact headlessly:
-   - `node packages/cli/bin/notis.js apps verify`
+   - `npx --package @notis_ai/cli@latest -- notis apps verify`
 6. For a brand-new app, create the remote app and link the project in one step:
-   - `node packages/cli/bin/notis.js apps create "My App" .`
+   - `npx --package @notis_ai/cli@latest -- notis apps create "My App" .`
 7. Or link the project to an existing remote app (skip if you used `pull` or `create`):
-   - `node packages/cli/bin/notis.js apps link`
+   - `npx --package @notis_ai/cli@latest -- notis apps link`
 8. Deploy the artifact to Notis:
-   - `node packages/cli/bin/notis.js apps deploy`
+   - `npx --package @notis_ai/cli@latest -- notis apps deploy`
 9. Check project health:
-   - `node packages/cli/bin/notis.js apps doctor`
+   - `npx --package @notis_ai/cli@latest -- notis apps doctor`
 
 ### App development rules
 
 - Always `build` before `deploy`; run `verify` before deploy when validating an app change.
-- Prefer `node packages/cli/bin/notis.js apps create "Name" .` for the first deploy of a new app.
+- Prefer `npx --package @notis_ai/cli@latest -- notis apps create "Name" .` for the first deploy of a new app.
 - Link before `deploy`, or pass `--app-id <id>` when intentionally deploying without writing local link state.
-- Use `node packages/cli/bin/notis.js apps doctor` to diagnose configuration or dependency issues.
-- Use `node packages/cli/bin/notis.js apps list` to discover existing app IDs before linking.
+- Use `npx --package @notis_ai/cli@latest -- notis apps doctor` to diagnose configuration or dependency issues.
+- Use `npx --package @notis_ai/cli@latest -- notis apps list` to discover existing app IDs before linking.
 - For App Store publishing, do not use the CLI. The user opens the app details page in the Notis Portal, sets visibility to Team or Public, then uses Publish/Update. The backend opens the registry PR on their behalf using a service token. Do not invent any CLI store-publish command.
 
 ### App development command reference
 
-- `node packages/cli/bin/notis.js apps list` -- list accessible apps
-- `node packages/cli/bin/notis.js apps init` -- scaffold a new Vite + React + `@notis/sdk` project
-- `node packages/cli/bin/notis.js apps pull <app-id> [dir] [--force] [--version <n>]` -- download the persisted source snapshot for an installed app and link the local directory to that app/version; legacy apps must be redeployed once with the current CLI before they can be pulled
-- `node packages/cli/bin/notis.js apps dev` -- discover local apps, register desktop-local dev sessions, and load them in the Electron Portal Local development sidebar group
-- `node packages/cli/bin/notis.js apps build` -- compile the production artifact
-- `node packages/cli/bin/notis.js apps verify` -- headless render-smoke packaged routes before deploy
-- `node packages/cli/bin/notis.js apps create` -- create a fresh remote app and optionally link the local project
-- `node packages/cli/bin/notis.js apps link` -- associate the project with a remote app
-- `node packages/cli/bin/notis.js apps deploy` -- upload the artifact and editable source snapshot to the linked installed app in Notis
-- `node packages/cli/bin/notis.js apps deploy --direct` -- deploy directly to Supabase storage, bypassing the backend server (auto-fallback when server is down)
-- `node packages/cli/bin/notis.js apps doctor` -- run project diagnostics
+- `npx --package @notis_ai/cli@latest -- notis apps list` -- list accessible apps
+- `npx --package @notis_ai/cli@latest -- notis apps init` -- scaffold a new Vite + React + `@notis/sdk` project
+- `npx --package @notis_ai/cli@latest -- notis apps pull <app-id> [dir] [--force] [--version <n>]` -- download the persisted source snapshot for an installed app and link the local directory to that app/version; legacy apps must be redeployed once with the current CLI before they can be pulled
+- `npx --package @notis_ai/cli@latest -- notis apps dev` -- discover local apps, register desktop-local dev sessions, and load them in the Electron Portal Local development sidebar group
+- `npx --package @notis_ai/cli@latest -- notis apps build` -- compile the production artifact
+- `npx --package @notis_ai/cli@latest -- notis apps verify` -- headless render-smoke packaged routes before deploy
+- `npx --package @notis_ai/cli@latest -- notis apps create` -- create a fresh remote app and optionally link the local project
+- `npx --package @notis_ai/cli@latest -- notis apps link` -- associate the project with a remote app
+- `npx --package @notis_ai/cli@latest -- notis apps deploy` -- upload the artifact and editable source snapshot to the linked installed app in Notis
+- `npx --package @notis_ai/cli@latest -- notis apps deploy --direct` -- deploy directly to Supabase storage, bypassing the backend server (auto-fallback when server is down)
+- `npx --package @notis_ai/cli@latest -- notis apps doctor` -- run project diagnostics
 
 App Store publishing is portal-only — there is no CLI publish command.
 
@@ -109,14 +104,14 @@ If the task is specifically about app structure, runtime behavior, or database/v
 
 ## IMPORTANT: When NOT to use tool access for app development
 
-When building or deploying a Notis app, do NOT use `notis tools exec` for any of these operations:
+When building or deploying a Notis app, do NOT use `npx --package @notis_ai/cli@latest -- notis tools exec` for any of these operations:
 
 - Creating databases -- declare them in `notis.config.ts` instead
-- Loading or saving app files -- use `notis apps build` and `notis apps deploy`
-- Linting app files -- use `notis apps build` which validates automatically
+- Loading or saving app files -- use `npx --package @notis_ai/cli@latest -- notis apps build` and `npx --package @notis_ai/cli@latest -- notis apps deploy`
+- Linting app files -- use `npx --package @notis_ai/cli@latest -- notis apps build` which validates automatically
 - Managing app routes -- write standard Vite + React pages in `app/`, not raw JS files
 
-The only `notis tools exec` calls that are valid during app development are for testing the app's runtime behavior after deployment (e.g., querying a database to verify data was created).
+The only `npx --package @notis_ai/cli@latest -- notis tools exec` calls that are valid during app development are for testing the app's runtime behavior after deployment (e.g., querying a database to verify data was created).
 
 ## Section 2: Accessing Tools Through the Notis CLI
 
@@ -132,29 +127,29 @@ This is the main escape hatch for:
 ### Tool access workflow
 
 1. List available toolkit namespaces:
-   - `notis tools toolkits`
+   - `npx --package @notis_ai/cli@latest -- notis tools toolkits`
 2. Search for the capability you need using natural language:
-   - `notis tools search "<query>"`
+   - `npx --package @notis_ai/cli@latest -- notis tools search "<query>"`
    - optionally narrow with `--toolkits <csv-or-json>`
 3. If needed, inspect the exact tool and parameter schema:
-   - `notis tools describe <tool-name>`
-   - `notis tools exec <tool-name> --get-schema`
+   - `npx --package @notis_ai/cli@latest -- notis tools describe <tool-name>`
+   - `npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --get-schema`
 4. Validate arguments before execution when the tool is mutating or the schema is non-trivial:
-   - `notis tools exec <tool-name> --dry-run --arguments '<json>'`
+   - `npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --dry-run --arguments '<json>'`
 5. Execute the tool:
-   - `notis tools exec <tool-name> --arguments '<json>'`
+   - `npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --arguments '<json>'`
 6. If multiple independent calls are needed, use:
-   - `notis tools exec-parallel '<json-array>'`
+   - `npx --package @notis_ai/cli@latest -- notis tools exec-parallel '<json-array>'`
 7. If the toolkit is not connected yet, generate the connection URL:
-   - `notis tools link <toolkit>`
+   - `npx --package @notis_ai/cli@latest -- notis tools link <toolkit>`
 
 ### Tool access rules
 
-- Never guess tool names. Discover them with `notis tools search` first.
-- Prefer first-class CLI commands when they exist, but use `notis tools ...` whenever the capability is not covered by a dedicated command.
-- When you know the tool name but not the argument shape, use `notis tools describe` or `--get-schema` before execution.
+- Never guess tool names. Discover them with `npx --package @notis_ai/cli@latest -- notis tools search` first.
+- Prefer first-class CLI commands when they exist, but use `npx --package @notis_ai/cli@latest -- notis tools ...` whenever the capability is not covered by a dedicated command.
+- When you know the tool name but not the argument shape, use `npx --package @notis_ai/cli@latest -- notis tools describe` or `--get-schema` before execution.
 - Use `--dry-run` before mutating calls when you want schema validation without execution.
-- If a toolkit is missing, use `notis tools link <toolkit>` to start the connection flow.
+- If a toolkit is missing, use `npx --package @notis_ai/cli@latest -- notis tools link <toolkit>` to start the connection flow.
 
 ### Toolkit mental model
 
@@ -176,35 +171,35 @@ The pattern is:
 Find a tool:
 
 ```bash
-notis tools toolkits
-notis tools search "list today's calendar events"
+npx --package @notis_ai/cli@latest -- notis tools toolkits
+npx --package @notis_ai/cli@latest -- notis tools search "list today's calendar events"
 ```
 
 Inspect a tool before execution:
 
 ```bash
-notis tools describe composio-googlecalendar-default-list_events
-notis tools exec composio-googlecalendar-default-list_events --get-schema
+npx --package @notis_ai/cli@latest -- notis tools describe composio-googlecalendar-default-list_events
+npx --package @notis_ai/cli@latest -- notis tools exec composio-googlecalendar-default-list_events --get-schema
 ```
 
 Dry-run a tool call:
 
 ```bash
-notis tools exec notis-default-query --dry-run --arguments '{"database_slug":"tasks","query":{"page_size":10}}'
-notis tools exec notis-default-get_database --dry-run --arguments '{"database_slug":"tasks"}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-query --dry-run --arguments '{"database_slug":"tasks","query":{"page_size":10}}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-get_database --dry-run --arguments '{"database_slug":"tasks"}'
 ```
 
 Execute a tool call:
 
 ```bash
-notis tools exec notis-default-query --arguments '{"database_slug":"tasks","query":{"page_size":10}}'
-notis tools exec notis-default-get_database --arguments '{"database_slug":"tasks"}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-query --arguments '{"database_slug":"tasks","query":{"page_size":10}}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-get_database --arguments '{"database_slug":"tasks"}'
 ```
 
 Connect a missing toolkit:
 
 ```bash
-notis tools link github
+npx --package @notis_ai/cli@latest -- notis tools link github
 ```
 
 ## Native database access
@@ -219,24 +214,24 @@ Native Notis databases are accessed through the generic tool workflow, not a fir
 Example workflow before building an app:
 
 ```bash
-notis tools search "list Notis databases"
-notis tools exec notis-default-list_databases --arguments '{}'
-notis tools exec notis-default-get_database --get-schema
-notis tools exec notis-default-get_database --arguments '{"database_slug":"social_media_calendar"}'
-notis tools exec notis-default-query --arguments '{"database_slug":"social_media_calendar","query":{"page_size":1}}'
+npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-list_databases --arguments '{}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-get_database --get-schema
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-get_database --arguments '{"database_slug":"social_media_calendar"}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-query --arguments '{"database_slug":"social_media_calendar","query":{"page_size":1}}'
 ```
 
 ## Supporting commands
 
-- `notis doctor` — verify CLI config, auth, and API reachability before relying on the CLI
-- `notis describe <command...>` — get the exact command contract for first-class CLI commands
+- `npx --package @notis_ai/cli@latest -- notis doctor` — verify CLI config, auth, and API reachability before relying on the CLI
+- `npx --package @notis_ai/cli@latest -- notis describe <command...>` — get the exact command contract for first-class CLI commands
 
 ## Summary
 
 Use `notis-cli` for two things:
 
-1. local app development through `notis apps ...`
-2. tool discovery and execution through `notis tools ...`
+1. local app development through `npx --package @notis_ai/cli@latest -- notis apps ...`
+2. tool discovery and execution through `npx --package @notis_ai/cli@latest -- notis tools ...`
 
 Most importantly: if you do not currently have the tool you need, especially for direct MCP or integration work, use the Notis CLI instead of treating the task as blocked.
 
@@ -246,11 +241,11 @@ Most importantly: if you do not currently have the tool you need, especially for
 
 The backend server at `http://localhost:3001` is not running. Solutions:
 
-1. Use `--direct` flag: `notis apps deploy --direct` uploads to Supabase storage directly
+1. Use `--direct` flag: `npx --package @notis_ai/cli@latest -- notis apps deploy --direct` uploads to Supabase storage directly
 2. Start the backend server: `cd server && python3 main.py`
-3. Check the API base: `notis doctor` shows the configured `api_base`
+3. Check the API base: `npx --package @notis_ai/cli@latest -- notis doctor` shows the configured `api_base`
 
-### `notis doctor` shows health/tool_roundtrip errors
+### `npx --package @notis_ai/cli@latest -- notis doctor` shows health/tool_roundtrip errors
 
 The CLI health check pings the backend server. If it's not running, these checks fail. App development commands that are `backend_call: local` (`init`, `build`, `verify`, `link`, `doctor`) work without the server. `dev`, `pull`, `create`, `list`, and normal `deploy` need the backend; `deploy --direct` can bypass it when Supabase credentials are available.
 

package/skills/notis-query/cli.md

@@ -1,10 +1,10 @@
 # Notis CLI — Database Tool Workflow
 
-Use the generic `notis tools` workflow for native Notis Database operations from the terminal. The dedicated database command group has been removed.
+Use the generic `notis tools` workflow through NPX for native Notis Database operations from the terminal. The dedicated database command group has been removed.
 
 ## Setup
 
-Install and sign into Notis Desktop. The desktop app installs the `notis` command and keeps the CLI profile current.
+Install and sign into Notis Desktop to keep the CLI profile current. Run the CLI through NPX, for example `npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"`.
 
 For CI, hosted agents, or internal scripts, pass a non-persisted token with `NOTIS_JWT=<token>` and use `--api-base <server-url>` when targeting a non-default server.
 
@@ -18,23 +18,23 @@ For CI, hosted agents, or internal scripts, pass a non-persisted token with `NOT
 ## Workflow
 
 ```bash
-notis tools search "list Notis databases"
-notis tools exec notis-default-list_databases --arguments '{}'
-notis tools exec notis-default-get_database --get-schema
-notis tools exec notis-default-get_database --arguments '{"database_slug":"tasks"}'
-notis tools exec notis-default-query --dry-run --arguments '{"database_slug":"tasks","query":{"page_size":10}}'
-notis tools exec notis-default-query --arguments '{"database_slug":"tasks","query":{"page_size":10}}'
+npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-list_databases --arguments '{}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-get_database --get-schema
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-get_database --arguments '{"database_slug":"tasks"}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-query --dry-run --arguments '{"database_slug":"tasks","query":{"page_size":10}}'
+npx --package @notis_ai/cli@latest -- notis tools exec notis-default-query --arguments '{"database_slug":"tasks","query":{"page_size":10}}'
 ```
 
 ## Supporting command
 
-### `notis doctor`
+### `npx --package @notis_ai/cli@latest -- notis doctor`
 
 Run a quick CLI health check for config, auth, and API reachability.
 
 When to use: Use this before relying on the CLI in automation or after changing environments.
 
 Examples:
-- `notis doctor`
-- `notis doctor --json`
+- `npx --package @notis_ai/cli@latest -- notis doctor`
+- `npx --package @notis_ai/cli@latest -- notis doctor --json`
 

package/src/cli.js

@@ -64,7 +64,16 @@ function attachSpec(program, parentMap, spec, specs) {
   }
 
   for (const option of spec.args_schema?.options || []) {
-    command.option(option.flags, option.description);
+    if (option.collect) {
+      command.option(
+        option.flags,
+        option.description,
+        (value, previous) => [...(previous || []), value],
+        [],
+      );
+    } else {
+      command.option(option.flags, option.description);
+    }
   }
 
   command.action(async (...raw) => {

package/src/command-specs/apps.js

@@ -381,8 +381,8 @@ export function buildEnsureDevInstallArguments({ appConfig, manifest, linkedStat
     name: appConfig.name,
     manifest,
   };
-  if (linkedState?.app_id) {
-    arguments_.app_id = linkedState.app_id;
+  if (linkedState?.dev_app_id) {
+    arguments_.app_id = linkedState.dev_app_id;
   }
   return arguments_;
 }

package/src/command-specs/helpers.js

@@ -44,12 +44,14 @@ export async function runToolCommand({
   arguments_ = {},
   mutating = false,
   idempotencyKey,
+  fileBindings = [],
 }) {
   const result = await callTool({
     runtime: { ...runtime, mutating },
     toolName,
     arguments_,
     idempotencyKey: mutating ? idempotencyKey : null,
+    fileBindings,
   });
   return result;
 }

package/src/command-specs/tools.js

@@ -1,4 +1,6 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { accessSync, constants as fsConstants, createReadStream, existsSync, readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename } from 'node:path';
 import { usageError } from '../runtime/errors.js';
 import {
   fetchToolkits,
@@ -42,6 +44,89 @@ const LONG_RUNNING_TOOL_NAMES = new Set([
   'notis-default-edit_image_gemini',
 ]);
 
+const EXTENSION_CONTENT_TYPES = new Map([
+  ['.pdf', 'application/pdf'],
+  ['.png', 'image/png'],
+  ['.jpg', 'image/jpeg'],
+  ['.jpeg', 'image/jpeg'],
+  ['.gif', 'image/gif'],
+  ['.webp', 'image/webp'],
+  ['.txt', 'text/plain'],
+  ['.csv', 'text/csv'],
+  ['.json', 'application/json'],
+  ['.md', 'text/markdown'],
+]);
+
+function guessContentType(filePath) {
+  const lower = filePath.toLowerCase();
+  const dotIndex = lower.lastIndexOf('.');
+  if (dotIndex === -1) return 'application/octet-stream';
+  return EXTENSION_CONTENT_TYPES.get(lower.slice(dotIndex)) || 'application/octet-stream';
+}
+
+async function hashFileSha256(localPath) {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(localPath)) {
+    hash.update(chunk);
+  }
+  return hash.digest('hex');
+}
+
+async function parseFileBindingSpec(spec, index) {
+  if (typeof spec !== 'string' || !spec.trim()) {
+    throw usageError('--file must be formatted as <argument-path>=<local-path>');
+  }
+
+  const equalsIndex = spec.indexOf('=');
+  if (equalsIndex <= 0 || equalsIndex === spec.length - 1) {
+    throw usageError('--file must be formatted as <argument-path>=<local-path>');
+  }
+
+  const argumentPath = spec.slice(0, equalsIndex).trim();
+  const localPath = spec.slice(equalsIndex + 1).trim();
+  if (!argumentPath) {
+    throw usageError('--file argument path is required');
+  }
+  if (!localPath) {
+    throw usageError('--file local path is required');
+  }
+  if (!existsSync(localPath)) {
+    throw usageError(`File not found: ${localPath}`);
+  }
+
+  let stats;
+  try {
+    stats = statSync(localPath);
+    accessSync(localPath, fsConstants.R_OK);
+  } catch {
+    throw usageError(`File is not readable: ${localPath}`);
+  }
+  if (!stats.isFile()) {
+    throw usageError(`File is not a regular file: ${localPath}`);
+  }
+
+  const sha256 = await hashFileSha256(localPath);
+  const fileBasename = basename(localPath);
+  const fieldName = `file_${index}`;
+
+  return {
+    argument_path: argumentPath,
+    field_name: fieldName,
+    basename: fileBasename,
+    size: stats.size,
+    sha256,
+    contentType: guessContentType(fileBasename),
+    localPath,
+  };
+}
+
+async function parseFileBindings(rawFileOptions) {
+  const values = Array.isArray(rawFileOptions)
+    ? rawFileOptions
+    : (rawFileOptions ? [rawFileOptions] : []);
+  return Promise.all(values.map((value, index) => parseFileBindingSpec(value, index)));
+}
+
 function ensureLongRunningToolTimeout(ctx, toolNames) {
   const names = Array.isArray(toolNames) ? toolNames : [toolNames];
   if (!names.some((name) => LONG_RUNNING_TOOL_NAMES.has(name))) {
@@ -124,6 +209,7 @@ async function toolsDescribeHandler(ctx) {
 async function toolsExecHandler(ctx) {
   ensureLongRunningToolTimeout(ctx, ctx.args.toolName);
   const toolkits = normalizeToolkits(ctx.options.toolkits);
+  const fileBindings = await parseFileBindings(ctx.options.file);
 
   if (ctx.options.getSchema) {
     const tool = await fetchToolSchema(ctx.runtime, ctx.args.toolName, ctx.options.toolkits);
@@ -144,6 +230,9 @@ async function toolsExecHandler(ctx) {
     : parseMaybeJson(rawArguments, 'arguments') || {};
 
   if (ctx.options.dryRun) {
+    if (fileBindings.length) {
+      throw usageError('--file is only supported when executing a tool, not with --dry-run');
+    }
     const tool = await fetchToolSchema(ctx.runtime, ctx.args.toolName, ctx.options.toolkits);
     const errors = validateArguments(tool.parameters, args);
 
@@ -181,6 +270,7 @@ async function toolsExecHandler(ctx) {
     },
     mutating: true,
     idempotencyKey,
+    fileBindings,
   });
 
   return ctx.output.emitSuccess({
@@ -193,6 +283,10 @@ async function toolsExecHandler(ctx) {
 }
 
 async function toolsExecParallelHandler(ctx) {
+  const parallelFileBindings = await parseFileBindings(ctx.options.file);
+  if (parallelFileBindings.length) {
+    throw usageError('--file is supported by `notis tools exec` only; exec-parallel accepts JSON calls without file uploads.');
+  }
   const calls = parseMaybeJson(ctx.args.calls, 'calls');
   if (!Array.isArray(calls) || !calls.length) {
     throw usageError('calls must be a non-empty JSON array of {tool_name, arguments} objects');
@@ -326,6 +420,7 @@ export const toolsCommandSpecs = [
       arguments: [{ token: '<tool-name>', description: 'Tool name returned by `notis tools search`.' }],
       options: [
         { flags: '--arguments <json>', description: 'JSON object, @file path, or - for stdin.' },
+        { flags: '--file <argument-path=local-path>', description: 'Upload a local file into a file-uploadable tool argument. Repeatable.', collect: true },
         { flags: '--get-schema', description: 'Display the tool parameter schema without executing.' },
         { flags: '--dry-run', description: 'Validate arguments against the tool schema without executing.' },
         { flags: '--toolkits <csv-or-json>', description: 'Optional toolkit namespace(s) to use when resolving the tool.' },
@@ -338,6 +433,7 @@ export const toolsCommandSpecs = [
       'notis tools exec notis-default-query --dry-run --arguments \'{"database_slug":"tasks","query":{}}\'',
       'notis tools exec notis-default-query --arguments @query.json',
       'notis tools exec notis-default-query --arguments - < query.json',
+      'notis tools exec composio-dropbox-default-upload_file --arguments \'{"path":"/target/in/dropbox.pdf"}\' --file content=./Invoice.pdf',
     ],
     output_schema: 'Returns the raw tool execution payload.',
     mutates: true,
@@ -354,7 +450,9 @@ export const toolsCommandSpecs = [
       arguments: [
         { token: '<calls>', description: 'JSON array of {tool_name, arguments} objects.' },
       ],
-      options: [],
+      options: [
+        { flags: '--file <argument-path=local-path>', description: 'Unsupported for exec-parallel; use tools exec for file uploads.', collect: true },
+      ],
     },
     examples: [
       'notis tools exec-parallel \'[{"tool_name":"notis-default-query","arguments":{"database_slug":"tasks","query":{}}},{"tool_name":"notis-default-list_databases","arguments":{}}]\'',

package/src/runtime/app-dev-server.js

@@ -114,8 +114,8 @@ function reactVersionFromPeer(peerRange) {
 function resolveHarnessReactVersion(projectDir) {
   const candidates = [
     join(projectDir, 'node_modules', '@notis', 'sdk', 'package.json'),
-    join(REPO_ROOT, 'packages', 'notis-sdk', 'package.json'),
-    join(CLI_ROOT, 'template', 'packages', 'notis-sdk', 'package.json'),
+    join(REPO_ROOT, 'packages', 'sdk', 'package.json'),
+    join(CLI_ROOT, 'template', 'packages', 'sdk', 'package.json'),
   ];
   for (const candidate of candidates) {
     const pkg = readJsonFile(candidate);

package/src/runtime/app-platform.js

@@ -27,6 +27,7 @@ const MONOREPO_APPS_DIR = resolve(CLI_ROOT, '../..', 'apps');
 const DIST_DIR = join(CLI_ROOT, 'dist');
 const SCAFFOLD_CATALOG_FILE = join(DIST_DIR, 'scaffolds.json');
 const SCAFFOLD_SOURCE_DIR = join(DIST_DIR, 'scaffolds');
+const TEMPLATE_SDK_DIR = join(CLI_ROOT, 'template', 'packages', 'sdk');
 export const NOTIS_APP_CATEGORIES = [
   'Productivity',
   'Sales & Marketing',
@@ -787,6 +788,7 @@ export function scaffoldProject({ projectDir, appName, fromSlug = null }) {
   if (existsSync(pkgPath)) {
     const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
     pkg.name = appName.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-');
+    ensureScaffoldLocalSdk(projectDir, pkg);
     writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
   }
 
@@ -821,6 +823,32 @@ export function scaffoldProject({ projectDir, appName, fromSlug = null }) {
   return { projectDir };
 }
 
+function ensureScaffoldLocalSdk(projectDir, pkg) {
+  let shouldInstallLocalSdk = false;
+  for (const dependencyGroup of ['dependencies', 'devDependencies']) {
+    const dependencyValue = pkg[dependencyGroup]?.['@notis/sdk'];
+    if (typeof dependencyValue === 'string' && dependencyValue.startsWith('file:')) {
+      pkg[dependencyGroup]['@notis/sdk'] = 'file:./packages/sdk';
+      shouldInstallLocalSdk = true;
+    }
+  }
+
+  if (!shouldInstallLocalSdk) {
+    return;
+  }
+
+  const localSdkDir = join(projectDir, 'packages', 'sdk');
+  if (existsSync(join(localSdkDir, 'package.json'))) {
+    return;
+  }
+  if (!existsSync(join(TEMPLATE_SDK_DIR, 'package.json'))) {
+    throw usageError(`SDK template not found at ${TEMPLATE_SDK_DIR}. Ensure @notis_ai/cli is installed correctly.`);
+  }
+
+  mkdirSync(dirname(localSdkDir), { recursive: true });
+  cpSync(TEMPLATE_SDK_DIR, localSdkDir, { recursive: true, dereference: true });
+}
+
 function resolveScaffoldSourceDir(fromSlug) {
   const bundledDir = join(SCAFFOLD_SOURCE_DIR, fromSlug);
   if (existsSync(bundledDir)) {