Docs
Open SmallForce

CLI

SmallForce CLI: Workspace commands

Search, read, and write UTF-8 text in the organization’s OS workspace

This page covers 3 smallforce workspace commands. It is generated from SmallForce CLI 0.1.17; run smallforce workspace --help (or any command with --help) to see the same reference for the version you have installed. New to the CLI? Start with installation and authentication and JSON output.

Agent workflow:
  1. Search semantically: smallforce workspace search "<question>" --json
  2. Read a result: smallforce workspace get <workspace-relative-path> --json
  3. Write only when the user asked for a change:
       smallforce workspace write <path> --content-file <local-file> --json

Paths are POSIX and workspace-relative. Search and get never expose the OS host's
absolute filesystem paths. write is UTF-8 text only, creates missing parent
folders, and fails on an existing file unless --overwrite is explicitly supplied.

Common options

Most commands accept these options as well as their own. Every command also accepts -h, --help.

OptionDescription
--api-key <key>SmallForce API key, or set SMALLFORCE_API_KEY
--backend-url <url>SmallForce backend URL, or set SMALLFORCE_BACKEND_URL
--jsonPrint stable machine-readable JSON
--textPrint human-readable text
--format <format>Output format: text or json

Run hybrid semantic and keyword search over indexed workspace files

Usage: smallforce workspace search [options] <query>

ArgumentDescription
queryQuestion or search phrase
OptionDescription
--path <path>Restrict search to a workspace-relative path
--limit <count>Matches to return, 1-20

Also accepts the common options listed at the top of this page.

Search returns matching snippets and workspace-relative paths. Treat medium- and
low-confidence results as candidates and verify them with workspace get.

Examples:
  $ smallforce workspace search "What did the customer say about pricing?"
  $ smallforce workspace search "Q3 launch plan" --path shared/plans --limit 10 --json

smallforce workspace get

Read an indexed workspace text document

Usage: smallforce workspace get [options] <path>

ArgumentDescription
pathWorkspace-relative path returned by search
OptionDescription
--offset <characters>Character offset, starting at 0
--max-chars <count>Maximum characters to return, up to 1000000

Also accepts the common options listed at the top of this page.

If truncated is true, call get again with offset + the returned text length.
This command reads indexed UTF-8 text; binary download is intentionally outside
the first workspace CLI surface.

Examples:
  $ smallforce workspace get shared/plans/q3.md
  $ smallforce workspace get shared/plans/q3.md --max-chars 20000 --json
  $ smallforce workspace get shared/plans/q3.md --offset 20000 --max-chars 20000 --json

smallforce workspace write

Write one UTF-8 text file into the workspace

Usage: smallforce workspace write [options] <path>

ArgumentDescription
pathPOSIX workspace-relative destination path
OptionDescription
--content <text>Inline UTF-8 text
--content-file <path>Read UTF-8 text from a local file, or - for stdin
--overwriteReplace the exact file when it already exists

Also accepts the common options listed at the top of this page.

Exactly one of --content or --content-file is required. Without --overwrite, an
existing destination returns a conflict and is never renamed or replaced. Parent
folders are created as needed. The OS requests immediate reindexing after write.

Examples:
  $ smallforce workspace write shared/notes/follow-up.md --content "Call Acme tomorrow"
  $ smallforce workspace write shared/reports/q3.md --content-file ./q3.md --json
  $ generate-report | smallforce workspace write shared/reports/q3.md --content-file - --overwrite --json