Manage stores

This page shows how to list, inspect, connect, create, unlock, retarget, log out of, and delete Loom stores from the command line.

Every command here is a loom verb. The loom_ prefix is optional, so loom list_stores and loom loom_list_stores are the same command. Commands that take parameters read them as a JSON object through --params. Add --store NAME to name the store for commands that act on a store's data; the store-management verbs (list_stores, current_default_store, load_store, unload_store, create_store, unlock_store, set_store_domain, logout) take the name in their parameters instead and reject --store with has no store parameter.

Where stores come from#

• Your first store comes from sign-in. Run loom setup or loom login; see Set up and log in. create_store cannot create a first store because it authenticates with a store you already have.
• More stores come from create_store, described below.

The seeded tutorial store's section name is loom_demo (with an underscore).

List your stores#

loom list_stores

The result has these fields:

See which store is the effective default:

loom current_default_store

It returns {"session_default": ..., "is_override": ...}; is_override is true only when a session has changed the default with load_store.

Describe a store#

loom describe_store --params '{"store":"coding"}'

This returns the store's description (in registry_description; from v0.674 the description key holds the same text when the server has none of its own, and earlier releases left it empty), its namespace scheme, fact counts by entity type, its custom types, and the running server's version (server_version_tag). Use it to pick the right store for a kind of data, or to confirm a server is new enough.

Load and unload a store#

A store other than the default must be connected before use. Agents do this with load_store. The loom command does it for you: when you pass --store NAME, it connects that store before running the command.

loom load_store --params '{"name":"kanban","set_default":false}'

set_default: true routes "default" to that store for the current session only. The loom command is a one-shot process, so use set_default through your agent, not the command line. Neither option changes stores.toml. Both name and set_default are required (omitting set_default exits 2: loom: missing a required argument: 'set_default').

Because each loom command is its own process, loom unload_store on the command line reports was_loaded: false; unloading matters only inside an agent session. Unloading an unknown name also exits 0 with was_loaded: false.

Disconnect a store you loaded:

loom unload_store --params '{"name":"kanban"}'

The primary store and the "default" alias cannot be unloaded. Trying exits 2 with cannot unload 'coding': it is the registered session primary or cannot unload 'default': it is the reserved session-primary alias.

Create a store#

loom create_store --params '{"name":"notes","usage":"Personal notes and preferences","domain":"PersonalDomain"}'

Creation is asynchronous. The command waits for the request to settle. From v0.672 a single status check that times out does not end the wait (it counts as "not yet" and the command keeps polling until its overall limit of about 120 seconds); the same holds for drop_store and unlock_store. Before that, one slow check could stop the command with a Python traceback The read operation timed out. status: "ok" means the store exists and its section is already written to stores.toml. Any other status, including pending after a timeout, means the store is not ready; keep the returned rid. The detail names the store and ends with may already exist on the server and the advice to run loom login to register it locally instead of retrying the create (on a private server the command reads loom login --base <origin>). Do not repeat the create: a second request makes a second store and spends another slot. The hint is not added to store_limit, denied, not_found, capacity_unavailable and default_forbidden, where no store was made.

Two behaviors to know:

• The name is normalized: My Notes 2 becomes the section my_notes_2. Without usage, the description is the generic Your Loom Cloud store.
• If stores.toml already has a section with that normalized name (the name lower-cased, anything other than letters, digits and _ turned into _, at most 30 characters), v0.674 and later refuse before sending any request: stores.toml already has a [notes] section; refusing to replace it. Remove or rename that section first, or choose another name. Nothing was created on the server. The result is status: error (exit 3) and no store slot is used. Earlier releases created a second store (..._2) on the server first and then failed to register it.
• An unrecognized domain is not rejected on creation; the store becomes a CodingDomain store. (set_store_domain does reject an unknown domain.) Check the domain you passed.

Change a store's domain#

A domain sets the capture and answering discipline for the store. Change it with:

loom set_store_domain --params '{"section":"notes","domain":"CodingDomain"}'

Use LogDomain for a Kanban board. See Concepts for what each domain means.

Unlock a store#

If the server reports a store as locked, recover it with:

loom unlock_store --params '{"section":"notes"}'

This waits until the store is ready. Credentials are never passed on the command line or printed. On a store that is not locked it simply returns status: ok.

A section name that is not in stores.toml returns status: error (exit 3). From v0.674, unlock_store and set_store_domain (and drop_store, exit 2) refuse it before any request with no store named '<name>' in <stores.toml path>. Configured: <sections>. On earlier releases a private install showed the misleading credential store 'coding' is connected to a different server than this request targets (a missing section counted as the hosted service) and the hosted service said cannot resolve the server-side handle for. logout says no store named ... is configured.

Log out of a store on this computer#

loom logout --params '{"section":"notes"}'

This removes that section, and its credential, from this computer's stores.toml. The store itself is untouched. (The result's server_status: "removed" refers to the local section, not to the server.)

Delete a store#

loom drop_store notes --confirm notes

This destroys the store and its contents on the server, then removes its section from stores.toml. It cannot be undone. --confirm must repeat the store's name exactly; without it the command prints a warning and exits 2 without contacting the server.

Add --json for one machine-readable result on stdout (progress goes to stderr). The server is the section's web_origin, so you normally need no other flag. --base URL is optional; if given, it must match that web_origin. drop_store does not read LOOM_WEB_BASE.

drop_store is a command-line verb only. It is deliberately not available to agents as a tool.

If the server does not report the store as dropped, the local section is kept and the command exits 3 (for example Still provisioning after 120s; the request may still complete.). The store may in fact be gone, so repeat the command only if loom list_stores still shows it.

From v0.672, when you drop the store whose own credentials authenticate the request (by default the first section in stores.toml), the server deletes those credentials as soon as the drop completes, so the status check starts being refused. The command then stops waiting, exits 3 and keeps the local section. With --json the result's detail says so (status is credentials_rejected):

The drop was queued and this store's credentials are no longer accepted, which normally means it was deleted. The local section [notes] was kept; remove it with `loom logout --params '{"section":"notes"}'`.

Without --json the command prints nothing, so read the exit status. The same refusal also answers a mismatched credential, so the command cannot be sure the store is gone: check with loom list_stores (or the web app), then run loom logout --params '{"section":"SECTION"}' for the kept section. To avoid this case, drop a store while the first section in stores.toml is a different one. A repeat on an already-dropped store exits 3 and keeps the section. Without --json it prints nothing; with --json the result has status: "not_found" and local_section_removed: false. Remove the leftover section with:

loom logout --params '{"section":"NAME"}'

From v0.674 the messages say "Loom store" (for example this DESTROYS the Loom store 'notes' and its contents), on a private server too; earlier releases said "hosted store".

A --base that does not match the section, a wrong --confirm, and an unreachable server (a connection error) exit 2. With --json, errors found before any request (unknown section, mismatched --base, wrong --confirm) and the closed-connection line below are still plain lines on stderr, not a JSON object. If the server closes the connection before answering, v0.674 and later print one line, loom drop_store: the server closed the connection before answering, so whether [notes] was dropped is unknown; your local section was kept. Check the store in your Loom web app before retrying., and exit 3; earlier releases showed a Python traceback instead.

Related pages#

• The stores.toml reference
• Save and load facts
• CLI reference