Feature: Workspace export/import for backup, migration, and sharing

[cybermaggedon]

Summary

Add CLI commands to export a workspace's full state as a portable bundle, and import it into another deployment. This enables backup/restore, migration between environments (dev → staging → prod), and sharing knowledge bases between teams.

Motivation

Currently there is no way to:

• Back up a workspace's configuration and knowledge before a risky change
• Move a workspace from one TrustGraph deployment to another
• Share a pre-configured workspace (prompts, tools, blueprints, agent patterns) as a starter kit

The building blocks exist — the config API has get_all / put_many, and the knowledge store has query/load interfaces — but there's no user-facing tooling to orchestrate a full export/import.

Proposed design

Please PR against the latest release/vX.Y branch.

Export

tg-export-workspace --workspace default --output workspace-default.tgx

Produces a single archive (e.g. tar.gz or zip) containing:

workspace-default.tgx/
├── manifest.json          # version, workspace id, export timestamp, TG version
├── config/                # all config entries
│   ├── prompt/            # one file per key
│   │   ├── extract-concepts.json
│   │   └── ...
│   ├── tool/
│   ├── flow-blueprint/
│   ├── agent-pattern/
│   ├── agent-task-type/
│   ├── collection/
│   └── ...
└── knowledge/             # optional, flag-controlled
    ├── triples.nq         # N-Quads dump of knowledge graph
    └── embeddings/        # serialised embeddings (format TBD)

Import

tg-import-workspace --input workspace-default.tgx --workspace staging

• --workspace optionally renames the workspace on import (default: use the name from the manifest)
• --overwrite flag to control whether existing keys are replaced or skipped (same semantics as WorkspaceInit's overwrite parameter)
• --config-only flag to skip knowledge import (useful for copying prompt/tool config without the data)

What to export

Phase 1 (config only):

• All config types: prompts, tools, blueprints, agent patterns, agent task types, collections, MCP configs, parameter types, interface descriptions, token costs
• This is the most immediately useful part and the simplest to implement

Phase 2 (knowledge):

• Triples from the knowledge graph (via triples client query)
• Document content from the librarian
• Embeddings (graph + document)
• This is larger in scope and may require streaming for large knowledge bases

Where it fits in the codebase

New CLI commands in trustgraph-cli/trustgraph/cli/:

trustgraph-cli/trustgraph/cli/
├── export_workspace.py    # new
└── import_workspace.py    # new

Both would use the existing gateway API (trustgraph-cli/trustgraph/api/) to interact with config-svc. The config API's get_all endpoint returns everything for a workspace in one call, and put_many can write it back.

Entry points

Add to pyproject.toml:

tg-export-workspace = "trustgraph.cli.export_workspace:main"
tg-import-workspace = "trustgraph.cli.import_workspace:main"

Implementation notes

• The archive format should be human-readable (JSON files in a directory structure) so users can inspect and hand-edit before importing
• Config values are stored as JSON strings in config-svc — export them pretty-printed for readability
• The manifest should include the TrustGraph version so import can warn about version mismatches
• For Phase 1, this is primarily a CLI exercise — no changes to the backend services needed

What you'll learn

• How TrustGraph's configuration system stores and retrieves workspace state
• The gateway API and how CLI tools interact with it
• How workspaces are structured and what config types exist
• CLI argument parsing patterns used throughout trustgraph-cli

References

• Existing CLI commands: trustgraph-cli/trustgraph/cli/ (see list_config_items.py, get_config_item.py, put_config_item.py for patterns)
• Gateway API client: trustgraph-cli/trustgraph/api/
• Config client: trustgraph-base/trustgraph/base/config_client.py (especially get_all and put_many)
• WorkspaceInit (similar overwrite logic): trustgraph-flow/trustgraph/bootstrap/initialisers/workspace_init.py

[sunnyadn]

Happy to take this one. One design question before I start: since the issue was filed, tg-export-workspace-config / tg-import-workspace-config have landed (curated 9-type subset → single JSON, "useful for cloning test setups"). Should the full .tgx bundle be an evolution of those commands, or new tg-export-workspace / tg-import-workspace with the config-only pair kept (or deprecated) as the lightweight path? I'd lean toward new commands matching the issue design — the bundle format and knowledge phase don't fit a single-JSON shape — but you know where you want the CLI surface to go.

Plan, following the issue:

Phase 1 (config-only) as its own PR — tg-export-workspace / tg-import-workspace under trustgraph-cli/trustgraph/cli/, using the config client's get_all / put_many over the gateway API, mirroring the arg parsing in list_config_items.py / put_config_item.py. Export writes manifest.json (with TG version) plus pretty-printed JSON per config key under config/<type>/; import supports --workspace rename, --overwrite (WorkspaceInit semantics), and --config-only.

Phase 2 (knowledge: triples / documents / embeddings) as a follow-up PR once Phase 1 lands.

Target release/v2.6 again?

[cybermaggedon]

Thanks for taking a look! Great analysis. Your plan looks perfect, target release/v2.6 again please. I don't think we have anything in the roadmap on config or workspace changes, but will coordinate if any changes arise. I'm happy with the 2 phase approach, feel free to do multiple PRs if that makes it easier for you.

tg-export-workspace-config / tg-import-workspace-config have landed (curated 9-type subset → single JSON, "useful for cloning test setups"). Should the full .tgx bundle be an evolution of those commands, or new tg-export-workspace / tg-import-workspace with the config-only pair kept (or deprecated) as the lightweight path? I'd lean toward new commands matching the issue design

Agreed. tg-import- and tg-export-workspace-config do one thing well (or at least OK). Fine for you to start with new ground rather than work around these commands.

[sunnyadn]

Both phases are merged now (#1019 config, #1024 knowledge) — happy for this to be closed. Thanks for the quick reviews!