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.
| Option | Description |
|---|---|
--api-key <key> | SmallForce API key, or set SMALLFORCE_API_KEY |
--backend-url <url> | SmallForce backend URL, or set SMALLFORCE_BACKEND_URL |
--json | Print stable machine-readable JSON |
--text | Print human-readable text |
--format <format> | Output format: text or json |
smallforce workspace search
Run hybrid semantic and keyword search over indexed workspace files
Usage: smallforce workspace search [options] <query>
| Argument | Description |
|---|---|
query | Question or search phrase |
| Option | Description |
|---|---|
--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>
| Argument | Description |
|---|---|
path | Workspace-relative path returned by search |
| Option | Description |
|---|---|
--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>
| Argument | Description |
|---|---|
path | POSIX workspace-relative destination path |
| Option | Description |
|---|---|
--content <text> | Inline UTF-8 text |
--content-file <path> | Read UTF-8 text from a local file, or - for stdin |
--overwrite | Replace 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