Kimura SCM

Appearance

KSCM Commands ​

Command Overview ​

KSCM uses a flat command list (no sub-commands). The first positional argument is the command name, followed by options. Options use the strict --key:value form, with --help or --h as the only flags. Use global help or per-command help to see the available options for each command.

text
kscm <command> [options]
kscm --help
kscm <command> --help

Auth context ​

Once login is performed, server, user, and password options are persisted and reused for subsequent commands. Most commands also allow you to re-enter login options to update them as needed.

text
kscm edit --workspace:<workspace-name> --file:./file.ext --user:<username> --pass:<password>

Workspace context ​

Most commands operate within a workspace context. If --workspace is omitted, KSCM attempts to infer the workspace from the current directory.

text
cd ~/path/to/workspace
kscm edit --file:./file.ext

If multiple workspaces match the current path, KSCM will require an explicit --workspace.

Commands ​

Auth & Session ​

Users & Groups ​

Repository ​

Workspace ​

History & Inspection ​

File Operations ​

Changelists ​

Attachments ​

Stashes ​

Submit ​

Skills & Integration ​

login ​

Authenticate to a KSCM server and save a login binding for subsequent commands.

Syntax ​

text
kscm login [options]

Required options ​

  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).

Optional options ​

  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use login once per environment or after credentials expire, so subsequent commands can run without repeating server and user credentials.

If you are already logged in, you can re-run login to refresh the saved login using the previously stored server and user.

Example ​

text
# First login (server/user required when no saved login exists)
kscm login --server:kimuraserver:8666 --user:alice --pass:MyPassword

# Re-login to refresh/update the saved binding
kscm login --server:kimuraserver:8666 --user:alice --pass:MyNewPassword

Back to Commands

logout ​

Remove the saved login binding.

Syntax ​

text
kscm logout

Required options ​

None.

Optional options ​

None.

Use case ​

Use logout when switching accounts or servers, or when you want to ensure subsequent commands do not reuse a previously saved login. If you are not logged in, logout prints a message and exits successfully.

Example ​

text
kscm logout

Back to Commands

show-oidc ​

Show the server OpenID Connect (OIDC) configuration.

Syntax ​

text
kscm show-oidc [options]

Required options ​

None.

Optional options ​

  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use show-oidc to inspect the effective server OIDC configuration used by SSO login.

Notes:

  • Requires server admin privileges.

Example ​

text
kscm show-oidc

Back to Commands

edit-oidc ​

Patch the server OpenID Connect (OIDC) configuration.

Syntax ​

text
kscm edit-oidc [oidc-options] [--clear:<csv-or-json>] [options]

Required options ​

  • At least one OIDC patch option or --clear.

OIDC patch options ​

  • --authority:<url>
  • --clientid:<id>
  • --audience:<value>
  • --scopes:<space-delimited-scopes>
  • --authorizeendpoint:<url>
  • --tokenendpoint:<url>
  • --redirecturi:<url>
  • --requirepkce:true|false
  • --usernameclaim:<claim-name>
  • --issuer:<issuer>
  • --clockskewseconds:<non-negative-int>
  • --clear:<csv-or-json> Clear specific fields by name.

Optional auth options ​

  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use edit-oidc to update only selected OIDC fields without replacing the whole configuration.

Notes:

  • Patch-by-default behavior: unspecified fields remain unchanged.
  • Use --clear to reset fields (CSV: authority,clientid or JSON: ["authority","clientid"]).
  • Requires server admin privileges.

Example ​

text
# Update authority and client id
kscm edit-oidc --authority:https://login.microsoftonline.com/<tenant>/v2.0 --clientid:<client-id>

# Clear optional endpoint overrides
kscm edit-oidc --clear:authorizeendpoint,tokenendpoint

Back to Commands

status ​

Show login status and (optionally) workspace status.

Syntax ​

text
kscm status [options]

Required options ​

None.

Optional options ​

  • --workspace:<name> Workspace name (if omitted, KSCM attempts to infer from the current directory).

Use case ​

Use status to confirm which user/server you are currently logged in as, and to quickly verify a workspace is reachable and up to date.

If a workspace is specified (or inferred), status refreshes the workspace and prints workspace details. If no workspace is specified or inferred, it prints login status only.

Example ​

text
# Login status only
kscm status

# Workspace status (explicit)
kscm status --workspace:MyWorkspace

# Workspace status (inferred from current directory)
cd ~/path/to/MyWorkspace
kscm status

Back to Commands

mcp ​

Run KSCM as a stdio MCP server.

mcp turns KSCM into a long-lived process that speaks MCP over stdio (JSON-RPC messages on stdin/stdout). This is the preferred long-lived integration mode for MCP-compatible tools and assistant/LLM workflows.

Syntax ​

text
kscm mcp

Required options ​

None.

Optional options ​

None.

Use case ​

Use mcp when an MCP client should invoke KSCM commands as tools through a persistent process instead of shelling out for each command.

Notes:

  • Runs until stdin closes, or until a client sends MCP shutdown and exits cleanly.
  • Tool calls are processed one at a time by the server process.
  • A workspace is loaded when a workspace-scoped tool is first invoked.
  • Only one workspace is kept in memory at a time.
  • If a later tool call targets a different workspace, KSCM unloads the current workspace and loads the requested workspace.
  • For repeated calls against the same workspace/context, KSCM reuses the loaded workspace to avoid reload overhead.
  • host-workspace remains available for legacy integrations that still depend on its JSONL protocol.

Example ​

text
# Start MCP server on stdio
kscm mcp

Back to Commands

host-server ​

Host a Kimura server process from KSCM.

host-server turns KSCM into a long-lived Kimura server host process using the built-in Kimura server bootstrap.

Syntax ​

text
kscm host-server [options]

Required options ​

None.

Optional options ​

  • --servername:<name> Server name (default: KIMURA).
  • --serverport:<port> Kimura server port (default: 8666).
  • --defaultfsport:<port> FS-DEFAULT port (default: 8667).
  • --serverlocation:<path> Server storage path (default: appdata Servers folder).
  • --defaultfslocation:<path> FS-DEFAULT storage path (default: appdata FileServers folder).

Use case ​

Use host-server when you want a local or scripted server host directly from kscm.

Notes:

  • Runs until Ctrl-C or process termination.
  • If no admin users exist and terminal input is interactive, KSCM prompts for admin creation.
  • If stdin is redirected, KSCM auto-creates a temporary admin user and prints credentials.
  • host-server is CLI-only and is not exposed as an MCP tool.

Example ​

text
# Start server with defaults
kscm host-server

# Start server with custom ports and storage
kscm host-server --servername:DEV-SERVER --serverport:9666 --defaultfsport:9667 --serverlocation:./ServerData --defaultfslocation:./FSDefaultData

Back to Commands

host-file-server ​

Host a standalone Kimura file server process from KSCM.

host-file-server turns KSCM into a long-lived standalone file server host process that connects to an existing Kimura server.

Syntax ​

text
kscm host-file-server --server:<host:port> --fsname:<name> --fspass:<password> [options]

Required options ​

  • --server:<host:port> Kimura server endpoint.
  • --fsname:<name> File server login name.
  • --fspass:<password> File server login password.

Optional options ​

  • --port:<port> Hosted file server TCP port (default: 8669).
  • --path:<path> File server storage root (default: appdata FileServers folder).
  • --trustedservercert:true|false Require trusted certificate from Kimura server (default: false).
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path (requires --certpfxpwd).
  • --certpfxpwd:<password> Client certificate PFX password (requires --certpfx).

Use case ​

Use host-file-server when you want to run a standalone file server node from CLI and connect it to an existing Kimura server.

Notes:

  • Hosted file server endpoint is always derived as localhost:<port>.
  • If no certificate options are provided, KSCM generates a self-signed certificate.
  • Runs until Ctrl-C or process termination.
  • Returns non-zero if file server initialization or connection fails.
  • host-file-server is CLI-only and is not exposed as an MCP tool.

Example ​

text
# Start standalone file server with defaults
kscm host-file-server --server:localhost:8666 --fsname:FS-A --fspass:Password

# Start with explicit storage path, port, and trust requirement
kscm host-file-server --server:kimura.example.com:8666 --fsname:FS-West --fspass:Password --port:9670 --path:./FileServers --trustedservercert:true

Back to Commands

list-users ​

List user accounts on the server.

Syntax ​

text
kscm list-users [options]

Required options ​

None.

Optional options ​

  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use list-users to discover available accounts and inspect login name, authentication mode, certificate requirement, group memberships, and last access.

Example ​

text
kscm list-users

Back to Commands

show-user ​

Show detailed information for one user account.

Syntax ​

text
kscm show-user --username:<name> [options]

Required options ​

  • --username:<name> User name.

Optional options ​

  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use show-user when you need one account's full details, including login name and group membership.

Example ​

text
kscm show-user --username:alice

Back to Commands

create-user ​

Create a user account.

Syntax ​

text
kscm create-user --username:<name> --loginname:<value> --auth:password|sso --group:<name> [options]

Required options ​

  • --username:<name> User name.
  • --loginname:<value> Required login identifier (for authentication/OIDC identity).
  • --auth:password|sso Authentication method.
  • --group:<name> Primary group.

Optional options ​

  • --password:<value> Password (required when --auth:password).
  • --groups:<csv-or-json> Additional groups (CSV or JSON list).
  • --requirecert:true|false Require certificate for user login (default: false).
  • --usercertthumbprint:<thumbprint> Required certificate thumbprint (requires --requirecert:true).
  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use create-user to provision a new account and initial group memberships.

Example ​

text
# Password user
kscm create-user --username:bob --loginname:bob@example.com --auth:password --password:StrongPass123 --group:Developers

# SSO user with additional groups
kscm create-user --username:carol --loginname:carol@example.com --auth:sso --group:Developers --groups:Artists,Reviewers

Back to Commands

edit-user ​

Edit one or more components of an existing user account. The user name and group memberships are unchanged.

Syntax ​

text
kscm edit-user --username:<name> [edit-options] [options]

Required options ​

  • --username:<name> User name.

At least one edit option is required.

Edit options ​

  • --loginname:<value> New login identifier.
  • --auth:password|sso Authentication method. When setting password, --password is required.
  • --password:<value> New password. A non-empty password is applied only when the resulting authentication method is password; switch an SSO account to password authentication with --auth:password and this option together.
  • --requirecert:true|false Require a client certificate for user login. Supplying this option updates the certificate settings and clears an unused thumbprint.
  • --usercertthumbprint:<thumbprint> Require a specific client certificate thumbprint. This option requires --requirecert:true.

Optional options ​

  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use edit-user when you need to update a user's login identifier, authentication method, password, or certificate requirement. All supplied edit options are applied as one user update.

Example ​

text
# Change the login identifier and password together
kscm edit-user --username:carol --loginname:carol@new-idp.example --auth:password --password:StrongPass123

# Switch to SSO authentication
kscm edit-user --username:carol --auth:sso

# Require a trusted client certificate with a specific thumbprint
kscm edit-user --username:carol --requirecert:true --usercertthumbprint:0123456789abcdef0123456789abcdef

Back to Commands

edit-user-groups ​

Edit an existing user's group memberships.

Syntax ​

text
kscm edit-user-groups --username:<name> [--add-groups:<csv-or-json>] [--remove-groups:<csv-or-json>] [options]

Required options ​

  • --username:<name> User name.
  • At least one of:
    • --add-groups:<csv-or-json>
    • --remove-groups:<csv-or-json>

Optional options ​

  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use edit-user-groups to grant or revoke membership for existing users.

Notes:

  • Strict behavior: the command fails if any requested group operation is invalid (unknown group, already assigned on add, not assigned on remove, or overlap between add/remove sets).
  • Group lists accept CSV (dev,artists) or JSON (["dev","artists"]).

Example ​

text
# Add groups
kscm edit-user-groups --username:alice --add-groups:Developers,Reviewers

# Remove groups
kscm edit-user-groups --username:alice --remove-groups:'["Artists"]'

# Add and remove in one call
kscm edit-user-groups --username:alice --add-groups:Developers --remove-groups:Reviewers

Back to Commands

delete-user ​

Delete a user account.

Syntax ​

text
kscm delete-user --username:<name> [options]

Required options ​

  • --username:<name> User name.

Optional options ​

  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use delete-user when deprovisioning an account.

Example ​

text
kscm delete-user --username:bob

Back to Commands

list-user-groups ​

List user groups on the server.

Syntax ​

text
kscm list-user-groups [options]

Required options ​

None.

Optional options ​

  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use list-user-groups to audit available groups and member counts.

Example ​

text
kscm list-user-groups

Back to Commands

create-user-group ​

Create a user group.

Syntax ​

text
kscm create-user-group --group:<name> [options]

Required options ​

  • --group:<name> Group name.

Optional options ​

  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use create-user-group before assigning users to a new access role.

Example ​

text
kscm create-user-group --group:Reviewers

Back to Commands

create-repo ​

Create a repository on the server.

Syntax ​

text
kscm create-repo --repository:<name> [options]

Required options ​

  • --repository:<name> Repository name.

Optional options ​

  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use create-repo when setting up a new project or repository on a KSCM server. This command typically requires server permissions to create repositories.

Example ​

text
# Create a repository (when already logged in)
kscm create-repo --repository:MyRepo

# Create a repository and provide login details (when not already logged in)
kscm create-repo --repository:MyRepo --server:kimuraserver:8666 --user:alice --pass:MyPassword

Back to Commands

list-repos ​

List repositories and their branches.

Syntax ​

text
kscm list-repos

Required options ​

None.

Optional options ​

  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use list-repos to discover repository names and available branches, or to confirm what is available on a server before creating a workspace.

Example ​

text
# List repositories and branches (when already logged in)
kscm list-repos

# List repositories and branches and provide login details (when not already logged in)
kscm list-repos --server:kimuraserver:8666 --user:alice --pass:MyPassword

Back to Commands

create-repomap ​

Create a repository map on the server.

Syntax ​

text
kscm create-repomap --name:<map-name> --path:<workspace-path> --repository:<repo-name> --branch:<branch-name> [options]

Required options ​

  • --name:<map-name> Repository map name.
  • --path:<workspace-path> Workspace path to map (for example /).
  • --repository:<repo-name> Repository name.
  • --branch:<branch-name> Branch name.

Optional options ​

  • --overwrite:true|false Overwrite existing map if it already exists (default: false).
  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use create-repomap to add a new reusable repository map for workspace creation and stash filtering scenarios.

Example ​

text
# Create a map with a root mapping
kscm create-repomap --name:Game-main --path:/ --repository:Game --branch:main

# Overwrite an existing map
kscm create-repomap --name:Game-main --path:/ --repository:Game --branch:release --overwrite:true

Back to Commands

edit-repomap ​

Edit an existing repository map on the server.

Syntax ​

text
kscm edit-repomap --name:<map-name> [--path:<workspace-path> --repository:<repo-name> --branch:<branch-name>] [--delete-path:<workspace-path>] [options]

Required options ​

  • --name:<map-name> Repository map name.

Optional options ​

  • --path:<workspace-path> Workspace path to set or update (requires --repository and --branch).
  • --repository:<repo-name> Repository name for --path.
  • --branch:<branch-name> Branch name for --path.
  • --delete-path:<workspace-path> Remove a path mapping (repeatable).
  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use edit-repomap for patch-style updates to existing maps without replacing all entries.

Notes:

  • At least one mutation is required (--path/--repository/--branch or --delete-path).
  • If one of --path, --repository, or --branch is provided, all three are required.
  • The root path / cannot be deleted.

Example ​

text
# Update one path mapping
kscm edit-repomap --name:Game-main --path:/Plugins --repository:Plugin --branch:main

# Delete a mapping path
kscm edit-repomap --name:Game-main --delete-path:/Plugins

Back to Commands

list-repomaps ​

List repository maps.

Syntax ​

text
kscm list-repomaps [options]

Required options ​

None.

Optional options ​

  • --mappings:true|false Print repo map entries (path, repository, branch) (default: false).
  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use list-repomaps to find which repository map name to pass to create-workspace. Add --mappings:true to see the map entries and understand how workspace paths map to repositories and branches.

Example ​

text
# List available repository maps
kscm list-repomaps

# Include map entries
kscm list-repomaps --mappings:true

Back to Commands

create-workspace ​

Create a local workspace configuration.

create-workspace saves workspace metadata in KSCM's app data so other commands can load the workspace and interact with it. It does not create or sync files by itself; run sync after creating a workspace.

Syntax ​

text
kscm create-workspace --name:<workspace-name> --path:<workspace-path> --repomap:<map-name> [options]

Required options ​

  • --name:<workspace-name> Workspace name.
  • --path:<workspace-path> Workspace root folder path.
  • --repomap:<map-name> Repository map name (validated against server info; see list-repomaps).

Optional options ​

  • --primaryfsname:<name> Primary file server name (default: FS-DEFAULT).
  • --primaryfsendpoint:<endpoint> Primary file server endpoint (default: first endpoint).
  • --secondaryfsname:<name> Secondary file server name (default: none).
  • --secondaryfsendpoint:<endpoint> Secondary file server endpoint (default: first endpoint).
  • --load:true|false Load the workspace after creating it (default: false).
  • --refresh:true|false Refresh after load (only if --load:true) (default: false).
  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use create-workspace when setting up a machine for the first time, or when you need a new workspace that points at a different repository map.

Notes:

  • KSCM validates the repository map name and file server settings against the server.
  • If --refresh:true is set, --load:true is also required.
  • The current implementation writes workspace metadata but does not automatically load or sync the workspace; use sync after creation.

Example ​

text
# Find a repository map name
kscm list-repomaps

# Create workspace metadata
kscm create-workspace --name:MyWorkspace --path:~/Dev/MyWorkspace --repomap:Main --server:kimuraserver:8666 --user:alice --pass:MyPassword

# Sync the workspace to latest
cd ~/Dev/MyWorkspace
kscm sync

# Create workspace metadata with explicit file server selection
kscm create-workspace --name:MyWorkspace --path:~/Dev/MyWorkspace --repomap:Main --primaryfsname:FS-DEFAULT --primaryfsendpoint:<primary-endpoint> --secondaryfsname:<secondary-fs-name> --secondaryfsendpoint:<secondary-endpoint>

Back to Commands

delete-workspace ​

Delete a workspace (local metadata only).

delete-workspace removes the local workspace metadata stored under KSCM's app data. It does not delete the workspace files from disk.

Syntax ​

text
kscm delete-workspace --workspace:<name>

Required options ​

  • --workspace:<name> Workspace name.

Optional options ​

None.

Use case ​

Use delete-workspace when you no longer need a workspace on this machine, or when you want to remove a stale/broken local workspace configuration and recreate it.

Notes:

  • Refuses to delete a workspace if it appears to be in use by another process.

Example ​

text
kscm delete-workspace --workspace:MyWorkspace

Back to Commands

list-workspaces ​

List all available local workspaces.

Syntax ​

text
kscm list-workspaces

Required options ​

None.

Optional options ​

None.

Use case ​

Use list-workspaces to see the workspace names available on this machine so you can reference one explicitly with --workspace:<name> when needed.

Notes:

  • This command lists local workspace metadata. It does not contact the server.

Example ​

text
kscm list-workspaces

Back to Commands

edit-workspace-settings ​

Edit local workspace settings.

edit-workspace-settings updates workspace metadata stored locally (it does not change server configuration). It is primarily used to adjust file server selection for an existing workspace.

Syntax ​

text
kscm edit-workspace-settings --workspace:<name> [options]

Required options ​

  • --workspace:<name> Workspace name.

Optional options ​

  • --primaryfsname:<name> Primary file server name (default: existing value).
  • --primaryfsendpoint:<endpoint> Primary file server endpoint (default: existing value).
  • --secondaryfsname:<name|none> Secondary file server name (default: existing value; use none to clear).
  • --secondaryfsendpoint:<endpoint> Secondary file server endpoint (default: existing value).
  • --server:<host:port> Server address (required if no saved login exists).
  • --user:<username> Username (required if no saved login exists).
  • --pass:<password> Password.
  • --trustedservercert:true|false Require server to provide a trusted certificate.
  • --certthumbprint:<thumbprint> Client certificate thumbprint.
  • --certpfx:<path> Client certificate PFX path.
  • --certpfxpwd:<password> Client certificate PFX password.

Use case ​

Use edit-workspace-settings when a workspace needs different file server endpoints (for example, switching to a closer mirror), or when you need to remove a configured secondary file server.

Notes:

  • You must specify at least one edit option (primaryfsname, primaryfsendpoint, secondaryfsname, or secondaryfsendpoint).
  • Refuses to edit while another process has the workspace loaded.

Example ​

text
# Update primary endpoint
kscm edit-workspace-settings --workspace:MyWorkspace --primaryfsendpoint:<primary-endpoint>

# Clear the secondary file server
kscm edit-workspace-settings --workspace:MyWorkspace --secondaryfsname:none

Back to Commands

show-workspace-settings ​

Show local workspace settings.

show-workspace-settings displays workspace metadata stored locally. It does not query the server.

Syntax ​

text
kscm show-workspace-settings [options]

Required options ​

None.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --tags:<csv-or-json> Filter by tags extracted from description (match any tag).
  • --clid:<id> Target workspace changelist id (default: 0).

Use case ​

Use show-workspace-settings to verify which repository map and file servers a workspace is configured to use, or to quickly check the workspace path and server binding.

Example ​

text
# Show settings for the workspace inferred from the current directory
cd ~/Dev/MyWorkspace
kscm show-workspace-settings

# Show settings for a specific workspace
kscm show-workspace-settings --workspace:MyWorkspace

Back to Commands

refresh ​

Refresh a workspace.

refresh updates local workspace state by asking the server for the latest information about the workspace and its files. It is commonly used before running other workspace commands.

Syntax ​

text
kscm refresh [options]

Required options ​

None.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).

Use case ​

Use refresh to make sure your local workspace state is current before checking status, syncing, or submitting changes.

Example ​

text
# Refresh workspace inferred from the current directory
cd ~/Dev/MyWorkspace
kscm refresh

# Refresh a specific workspace
kscm refresh --workspace:MyWorkspace

Back to Commands

reconcile ​

Reconcile and list workspace differences.

reconcile scans the workspace and reports files that are modified, missing, extra, or not at the latest revision.

Syntax ​

text
kscm reconcile [options]

Required options ​

None.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --modified:true|false Show modified files.
  • --missing:true|false Show missing files.
  • --extra:true|false Show extra files.
  • --notlatest:true|false Show files not at the latest revision.
  • --summary:true|false Print summary counts (default: true).

Use case ​

Use reconcile to quickly find workspace drift before syncing or submitting, or to audit which files differ from the server.

Notes:

  • If no category filter is specified, all categories are shown.
  • A file may appear in multiple categories.

Example ​

text
# Reconcile the inferred workspace
cd ~/Dev/MyWorkspace
kscm reconcile

# Only show missing and extra files
kscm reconcile --missing:true --extra:true

Back to Commands

sync ​

Sync files to a revision.

sync downloads files for a workspace to match a specific revision changelist (--clid) or the latest revision.

Syntax ​

text
kscm sync [options]

Required options ​

None.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --clid:<id> Revision changelist id (default: 0 = latest).
  • --force:true|false Force sync (default: false).
  • --clfiles:true|false Sync only files that are part of --clid (default: false).
  • --file:<path> Single file path (optional).
  • --files:<list> File list: JSON (["a","b"]) or CSV (a,b) (optional).
  • --directory:<path> Directory path (optional; may also be a JSON list).
  • --destination:<path> Download destination path (optional).

Use case ​

Use sync to bring your workspace up to date, to roll back to an older revision for testing, or to sync only a subset of files/directories.

Notes:

  • If neither --file/--files nor --directory is specified, KSCM syncs the entire workspace.
  • --directory can be a single path or a JSON list (for example ["a","b"] or {"a","b"}).
  • If --clfiles:true is set, --clid must be a changelist id greater than 0.
  • If --destination is set, files are downloaded there and workspace revision state is not updated.

Example ​

text
# Sync entire workspace to latest
cd ~/Dev/MyWorkspace
kscm sync

# Sync a specific file
kscm sync --file:./Content/Example.uasset

# Sync a directory
kscm sync --directory:./Content

# Sync to a specific revision changelist id
kscm sync --clid:12345

# Sync only files that belong to CL 12345
kscm sync --clid:12345 --clfiles:true

# Force sync (overwrite local state as needed)
kscm sync --force:true

# Download selected files to a temp folder (without changing workspace revision state)
kscm sync --file:./Content/Example.uasset --clid:12345 --destination:/tmp/kscm-compare

Back to Commands

clean-workspace ​

Clean a workspace to a revision.

clean-workspace removes local file operations, deletes extra files, and force-syncs the workspace to a specific revision changelist (--clid) or the latest revision.

Syntax ​

text
kscm clean-workspace [options]

Required options ​

None.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --clid:<id> Revision changelist id (default: 0 = latest).

Use case ​

Use clean-workspace to return a workspace to a pristine state that matches a specific revision, discarding local changes.

Notes:

  • This operation is destructive; local modifications and extra files will be removed.

Example ​

text
# Clean the entire workspace to latest
cd ~/Dev/MyWorkspace
kscm clean-workspace

# Clean to a specific revision changelist id
kscm clean-workspace --clid:12345

Back to Commands

host-workspace ​

Run KSCM as a long-lived workspace host process.

host-workspace turns KSCM into a long-lived process that reads JSONL requests from stdin and writes JSONL responses to stdout. This mode is primarily kept for legacy integrations (for example, older Unreal Engine plugin flows) that already use this protocol.

Syntax ​

text
kscm host-workspace

Required options ​

None.

Optional options ​

None.

Use case ​

Use host-workspace when an existing integration already depends on the host-workspace JSONL protocol and needs a persistent KSCM process.

Notes:

  • Runs until it receives exit or stop on stdin, or stdin closes.
  • The request/response format is JSONL (one JSON object per line).
  • For new long-lived integrations, prefer mcp.

Example ​

text
# Start the host (expects JSONL input on stdin)
kscm host-workspace

# Stop the host (send on stdin)
exit

history ​

List revision history.

history prints revision changelists for a workspace. You can target the entire workspace (default), a specific file, multiple files, or a specific directory.

Syntax ​

text
kscm history --file:<path> [options]
kscm history --files:<list> [options]
kscm history --directory:<path> [options]
kscm history [options]

Required options ​

None.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --file:<path> Single file path (relative to the current directory, or absolute).
  • --files:<list> File list: JSON (["a","b"]) or CSV (a,b). Paths are relative to the current directory, or absolute.
  • --directory:<path> Single directory path (relative to the current directory, or absolute).
  • --count:<n> Number of revisions to show (default: 50).

Use case ​

Use history to find a revision changelist id (clid) to inspect with show-revision, or to review recent changes for a file or folder.

Notes:

  • --directory cannot be combined with --file or --files.
  • --file and --files can be combined.
  • If neither --file, --files, nor --directory is specified, KSCM shows the workspace root history.
  • When using --file, output includes the operation and revision number for that file.
  • When multiple files are requested, output is grouped by file and --count applies to each file.

Example ​

text
# Workspace history (inferred workspace)
cd ~/Dev/MyWorkspace
kscm history

# File history
kscm history --file:./Source/MyFile.cpp --count:20

# Multiple file histories
kscm history --files:'["./Source/A.cpp","./Source/B.cpp"]' --count:5

# Directory history
kscm history --directory:./Source --count:50

Back to Commands

show-revision ​

Show details for a revision changelist.

show-revision prints revision metadata and the list of operations in a revision changelist (clid) for the current workspace.

Syntax ​

text
kscm show-revision --clid:<id> [options]

Required options ​

  • --clid:<id> Revision changelist id.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).

Use case ​

Use show-revision after history to inspect a specific revision in more detail, including the files that changed.

Example ​

text
# Show revision details in the inferred workspace
cd ~/Dev/MyWorkspace
kscm show-revision --clid:12345

# Show revision details for a specific workspace
kscm show-revision --workspace:MyWorkspace --clid:12345

Back to Commands

add ​

Mark files and directories for add.

add schedules new files (or all eligible files under a directory) to be included in the next submission from the workspace.

Syntax ​

text
kscm add --file:<path> [options]
kscm add --files:<list> [options]
kscm add --directory:<path-or-list> [options]

Required options ​

  • --file:<path> Single file path, or
  • --files:<list> File list: JSON (["a","b"]) or CSV (a,b), or
  • --directory:<path-or-list> Directory path, or JSON list of directory paths.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --clid:<id> Target workspace changelist id (default: 0).

Use case ​

Use add after creating new files in your workspace so they are tracked and can be submitted.

Marking files for add also signals to other users that you intend to introduce those files as part of your upcoming changes.

Notes:

  • File paths are interpreted relative to the current directory. KSCM resolves them to full paths before processing.

Example ​

text
# Add a single file
kscm add --file:./Content/NewAsset.uasset

# Add multiple files
kscm add --files:{"./a.txt","./b.txt"}

# Add all new files under a directory
kscm add --directory:./Content/NewFolder

# Add multiple directories
kscm add --directory:{"./Content/A","./Content/B"}

# Add a file to a specific changelist
kscm add --file:./Content/NewAsset.uasset --clid:123

# Add a directory to a specific changelist
kscm add --directory:./Content/NewFolder --clid:123

Back to Commands

edit ​

Mark files and directories for edit.

edit checks out files for editing in the workspace. It can also operate on directories (to select eligible files under those directories). Optionally, it can lock files so other users can still edit locally, but cannot submit new revisions while the lock is held (when supported by server policy).

Syntax ​

text
kscm edit --file:<path> [options]
kscm edit --files:<list> [options]
kscm edit --directory:<path-or-list> [options]

Required options ​

  • --file:<path> Single file path, or
  • --files:<list> File list: JSON (["a","b"]) or CSV (a,b), or
  • --directory:<path-or-list> Directory path, or JSON list of directory paths.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --clid:<id> Target workspace changelist id (default: 0).
  • --lock:true|false Lock files (default: false).

Use case ​

Use edit before modifying an existing file so KSCM can track the change and include it in a changelist and submission.

Marking a file for edit also signals to other users that you intend to modify that file.

Notes:

  • File paths are interpreted relative to the current directory. KSCM resolves them to full paths before processing.

Example ​

text
# Edit a single file
kscm edit --file:./Source/MyFile.cpp

# Edit multiple files
kscm edit --files:{"./a.txt","./b.txt"}

# Edit all eligible files under a directory
kscm edit --directory:./Source

# Edit multiple directories
kscm edit --directory:{"./Source","./Plugins"}

# Edit and lock a file
kscm edit --file:./Content/Example.uasset --lock:true

# Edit a file in a specific changelist
kscm edit --file:./Source/MyFile.cpp --clid:123

Back to Commands

delete ​

Mark files and directories for delete.

delete schedules files to be deleted as part of a future submission from the workspace. It can also operate on directories (to select eligible files under those directories).

Syntax ​

text
kscm delete --file:<path> [options]
kscm delete --files:<list> [options]
kscm delete --directory:<path-or-list> [options]

Required options ​

  • --file:<path> Single file path, or
  • --files:<list> File list: JSON (["a","b"]) or CSV (a,b), or
  • --directory:<path-or-list> Directory path, or JSON list of directory paths.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --clid:<id> Target workspace changelist id (default: 0).

Use case ​

Use delete when you want to remove files from the repository in your next submission.

Marking files for delete also signals to other users that you intend to remove those files as part of your upcoming changes.

Notes:

  • File paths are interpreted relative to the current directory. KSCM resolves them to full paths before processing.

Example ​

text
# Delete a single file
kscm delete --file:./Content/OldAsset.uasset

# Delete multiple files
kscm delete --files:{"./a.txt","./b.txt"}

# Delete all eligible files under a directory
kscm delete --directory:./Content/OldAssets

# Delete multiple directories
kscm delete --directory:{"./Content/OldA","./Content/OldB"}

# Delete a file in a specific changelist
kscm delete --file:./Content/OldAsset.uasset --clid:123

Back to Commands

move ​

Move one tracked file or directory to a new path inside the same repository.

The operation is recorded as a paired source delete and destination add so the server preserves the file identity and move history.

Syntax ​

text
kscm move --file:<source> --destination:<path> [options]
kscm move --directory:<source> --destination:<path> [options]

Required options ​

  • --file:<path> Source file, or
  • --directory:<path> Source directory.
  • --destination:<path> Destination file or directory path.

Specify exactly one source. The source and destination must remain inside the same repository.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --clid:<id> Target workspace changelist id (default: 0, the default changelist).

Examples ​

text
cd ~/Dev/MyWorkspace

# Move one file
kscm move --file:Source/OldName.cpp --destination:Source/NewName.cpp

# Move a directory into another directory path
kscm move --directory:Assets/Old --destination:Assets/New

# Put the move in an existing workspace changelist
kscm move --file:Source/OldName.cpp --destination:Source/NewName.cpp --clid:123

Back to Commands

revert ​

Revert file and directory operations.

revert cancels pending file operations (such as add/edit/delete) for the specified files (or for eligible files under a directory) in the workspace.

Syntax ​

text
kscm revert --file:<path> [options]
kscm revert --files:<list> [options]
kscm revert --directory:<path-or-list> [options]

Required options ​

  • --file:<path> Single file path, or
  • --files:<list> File list: JSON (["a","b"]) or CSV (a,b), or
  • --directory:<path-or-list> Directory path, or JSON list of directory paths.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --unchanged:true|false When true, revert only selected local edit operations whose files are present and content-identical to their current workspace revision (default: false).

Use case ​

Use revert when you want to undo pending operations on a file (for example, if you marked a file for edit or delete by mistake).

Notes:

  • If a file is marked for edit and has local modifications, revert also discards those modifications.
  • With --unchanged:true, modified or missing files are left untouched. Pending add, delete, and move operations are also left untouched.
  • File paths are interpreted relative to the current directory. KSCM resolves them to full paths before processing.

Example ​

text
# Revert a single file
kscm revert --file:./Source/MyFile.cpp

# Revert multiple files
kscm revert --files:{"./a.txt","./b.txt"}

# Revert operations under a directory
kscm revert --directory:./Source

# Revert only unchanged local edits under a directory
kscm revert --directory:./Source --unchanged:true

Back to Commands

list-ops ​

List active file operations.

list-ops shows files currently marked for add/edit/delete (and related operations) in the workspace, including who initiated the operation.

Syntax ​

text
kscm list-ops [options]

Required options ​

None.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --user:<name> Filter by a single user.
  • --users:<csv> Filter by a comma-separated list of users.
  • --contains:<text> Filter by filename substring.
  • --refresh:true|false Refresh file operations before listing (default: true).

Use case ​

Use list-ops to review what will be included in a changelist/submission, or to see if someone else is already working on the same files.

Example ​

text
# List all operations in the inferred workspace
cd ~/Dev/MyWorkspace
kscm list-ops

# Filter by user
kscm list-ops --user:alice

# Filter by filename substring
kscm list-ops --contains:Example

# Avoid refreshing before listing (faster, but may be stale)
kscm list-ops --refresh:false

Back to Commands

create-workspace-cl ​

Create a workspace changelist.

Changelists group file operations (add/edit/delete) into a named unit that can later be submitted.

Syntax ​

text
kscm create-workspace-cl --description:<text> [options]

Required options ​

  • --description:<text> Description.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).

Use case ​

Use create-workspace-cl when you want to group a set of operations into a separate changelist (for example, one changelist per feature or bug fix).

Example ​

text
cd ~/Dev/MyWorkspace

# Create a changelist with a description
kscm create-workspace-cl --description:"Fix build warnings"

# Create a changelist with a description
kscm create-workspace-cl --description:"Upgrade dependency X"

Back to Commands

list-workspace-cls ​

List workspace changelists.

Syntax ​

text
kscm list-workspace-cls [options]

Required options ​

None.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).

Use case ​

Use list-workspace-cls to find a changelist id (clid) to inspect, edit, delete, or submit.

Notes:

  • Output includes changelist id, name, operation count, and a short description.
  • The default changelist is marked with *.

Example ​

text
cd ~/Dev/MyWorkspace
kscm list-workspace-cls

# Only changelists with any matching tag in their description
kscm list-workspace-cls --tags:review,urgent

Back to Commands

show-workspace-cl ​

Show changelist details.

show-workspace-cl prints changelist metadata and can optionally include all file operations in the changelist.

Syntax ​

text
kscm show-workspace-cl --clid:<id> [options]

Required options ​

  • --clid:<id> Workspace changelist id (or name like default).

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --ops:true|false Print all operations in the changelist (default: false).

Use case ​

Use show-workspace-cl to review what is in a changelist before submitting, or to inspect a changelist id returned by list-workspace-cls.

Notes:

  • Options must use the strict --key:value form; use --ops:true (not --ops).

Example ​

text
cd ~/Dev/MyWorkspace

# Show details for the default changelist
kscm show-workspace-cl --clid:default

# Show details including operations
kscm show-workspace-cl --clid:123 --ops:true

Back to Commands

edit-workspace-cl ​

Edit a workspace changelist.

edit-workspace-cl updates the description of an existing workspace changelist.

Syntax ​

text
kscm edit-workspace-cl --clid:<id> --description:<text> [options]

Required options ​

  • --clid:<id> Workspace changelist id (or name like default).
  • --description:<text> Description.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).

Use case ​

Use edit-workspace-cl to update a changelist description before submitting it, or to keep changelist descriptions consistent for reviews and auditing.

Notes:

  • The default changelist cannot be modified.

Example ​

text
cd ~/Dev/MyWorkspace

# Update the description for a changelist id
kscm edit-workspace-cl --clid:123 --description:"Fix build warnings (Windows)"

Back to Commands

delete-workspace-cl ​

Delete a workspace changelist.

Syntax ​

text
kscm delete-workspace-cl --clid:<id> [options]

Required options ​

  • --clid:<id> Workspace changelist id.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).

Use case ​

Use delete-workspace-cl to remove an unused or incorrect changelist before it is submitted.

Notes:

  • By default, deleting a changelist does not revert the operations it contains.
  • By default, operations from a deleted changelist are moved to the default changelist.
  • The default changelist cannot be deleted.

Example ​

text
cd ~/Dev/MyWorkspace
kscm delete-workspace-cl --clid:123

Back to Commands

list-attachments ​

List attachments on a repo changelist, workspace changelist, or stash.

Syntax ​

text
kscm list-attachments --target:repo|workspace-cl|stash [options]

Required options ​

  • --target:repo|workspace-cl|stash Attachment target.
  • --clid:<id> Changelist id (repo/workspace-cl scopes).
  • --id:<number> Numeric stash ID (stash scope).

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --stash-scope:all|local|remote Restrict stash scope (default: all).
  • --revision:<n> Stash revision (0 = latest, otherwise 1..N).

Use case ​

Use list-attachments to discover which attachments exist before downloading or deleting them.

Examples ​

text
# Repo changelist attachments
kscm list-attachments --target:repo --clid:12345

# Workspace changelist attachments
kscm list-attachments --target:workspace-cl --clid:default

# Stash attachments
kscm list-attachments --target:stash --id:1030 --stash-scope:remote --revision:0

Back to Commands

upload-attachment ​

Upload an attachment to a repo changelist, workspace changelist, or stash.

Syntax ​

text
kscm upload-attachment --target:repo|workspace-cl|stash --file:<path> [options]

Required options ​

  • --target:repo|workspace-cl|stash Attachment target.
  • --file:<path> File to upload.
  • --clid:<id> Changelist id (repo/workspace-cl scopes).
  • --id:<number> Numeric stash ID (stash scope).

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --stash-scope:all|local|remote Restrict stash scope (default: all).
  • --revision:<n> Stash revision (0 = latest, otherwise 1..N).

Use case ​

Use upload-attachment to attach build artifacts, review notes, or other files.

Notes:

  • The attachment key is always the file name.

Examples ​

text
# Repo changelist attachment
kscm upload-attachment --target:repo --clid:12345 --file:./Reports/ReviewNotes.txt

# Workspace changelist attachment
kscm upload-attachment --target:workspace-cl --clid:default --file:./Reports/ReviewNotes.txt

# Stash attachment
kscm upload-attachment --target:stash --id:1030 --file:./Reports/ReviewNotes.txt --stash-scope:local

Back to Commands

download-attachment ​

Download an attachment from a repo changelist, workspace changelist, or stash.

Syntax ​

text
kscm download-attachment --target:repo|workspace-cl|stash --key:<key> --out:<path> [options]

Required options ​

  • --target:repo|workspace-cl|stash Attachment target.
  • --key:<key> Attachment key.
  • --out:<path> Output file or directory.
  • --clid:<id> Changelist id (repo/workspace-cl scopes).
  • --id:<number> Numeric stash ID (stash scope).

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --stash-scope:all|local|remote Restrict stash scope (default: all).
  • --revision:<n> Stash revision (0 = latest, otherwise 1..N).

Use case ​

Use download-attachment to retrieve a file attached to a changelist or stash.

Notes:

  • If --out is a directory (or ends with a slash), the attachment is saved as <key> inside it.

Examples ​

text
# Repo changelist attachment
kscm download-attachment --target:repo --clid:12345 --key:ReviewNotes.txt --out:./Downloads/ReviewNotes.txt

# Workspace changelist attachment
kscm download-attachment --target:workspace-cl --clid:default --key:ReviewNotes.txt --out:./Downloads/

# Stash attachment
kscm download-attachment --target:stash --id:1030 --key:ReviewNotes.txt --out:./Downloads/ --stash-scope:remote

Back to Commands

delete-attachment ​

Delete an attachment from a repo changelist, workspace changelist, or stash.

Syntax ​

text
kscm delete-attachment --target:repo|workspace-cl|stash --key:<key> [options]

Required options ​

  • --target:repo|workspace-cl|stash Attachment target.
  • --key:<key> Attachment key.
  • --clid:<id> Changelist id (repo/workspace-cl scopes).
  • --id:<number> Numeric stash ID (stash scope).

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --stash-scope:all|local|remote Restrict stash scope (default: all).
  • --revision:<n> Stash revision (0 = latest, otherwise 1..N).

Use case ​

Use delete-attachment to remove an attachment.

Examples ​

text
# Repo changelist attachment
kscm delete-attachment --target:repo --clid:12345 --key:ReviewNotes.txt

# Stash attachment
kscm delete-attachment --target:stash --id:1030 --key:ReviewNotes.txt --stash-scope:local

Back to Commands

list-stashes ​

List stashed changelists.

Syntax ​

text
kscm list-stashes [options]

Required options ​

None.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --scope:all|local|remote Filter by stash scope (default: all).
  • --createdby:<text> Filter by stash author (substring match).
  • --repomap:<name> Filter by repository map name.
  • --tags:<csv-or-json> Filter by tags extracted from description (match any tag).

Use case ​

Use list-stashes to find stash IDs to inspect with show-stash or restore with retrieve-stash, especially when switching machines or recovering work.

Notes:

  • Always refreshes remote stashes from the server before listing.
  • Output does not include stash GUIDs or branches.
  • --scope controls where KSCM searches:
    • local searches stashes stored locally on this machine.
    • remote searches stashes stored on the server.
    • all searches both.
  • Only stashes accessible to your user account will be shown.
  • --tags supports CSV (for example review,urgent) or JSON (for example ["review","urgent"]).

Example ​

text
# List all stashes
kscm list-stashes

# Only remote stashes created by a user, with any matching tag
kscm list-stashes --scope:remote --createdby:alice --tags:review,urgent

Back to Commands

stash-changelist ​

Stash a workspace changelist.

stash-changelist creates a new stash from a changelist. Stash IDs are assigned by the server, but you can target an existing stash by ID to replace it or add a new revision.

Syntax ​

text
kscm stash-changelist --clid:<id> --description:<text> [options]

Required options ​

  • --clid:<id> Workspace changelist id (or name like default).
  • --description:<text> Stash description.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --scope:local|remote Stash scope (default: local).
  • --id:<number> Update an existing stash by numeric ID.
  • --replace:true|false Replace an existing stash when using --id (default: false).
  • --owners:<csv-or-json> Owners (usernames, CSV or JSON list).
  • --viewers:<csv-or-json> Viewers (usernames, CSV or JSON list).
  • --updatecldesc:true|false Update changelist description (default: false).

Use case ​

Use stash-changelist to save work in progress from a changelist into a local or remote stash.

Notes:

  • Stash IDs are server-assigned; --id only selects an existing stash to replace or revise.
  • --replace:false creates a new revision of the selected stash ID.
  • Remote stashes always refresh from the server before stashing.

Example ​

text
# Stash a changelist locally
kscm stash-changelist --clid:123 --description:"WIP: refactor"

# Stash a changelist remotely
kscm stash-changelist --clid:123 --description:"WIP: refactor" --scope:remote

# Add a new revision to an existing stash by ID
kscm stash-changelist --clid:123 --description:"WIP: refactor v2" --id:1030

# Replace an existing stash by ID
kscm stash-changelist --clid:123 --description:"WIP: reset" --id:1030 --replace:true

Back to Commands

show-stash ​

Show stash details and operations.

show-stash prints metadata and operations for a stash ID. If a stash has multiple revisions, you can show a specific revision by number (1..N, where N is the latest).

Syntax ​

text
kscm show-stash --id:<number> [options]

Required options ​

  • --id:<number> Numeric stash ID.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --scope:all|local|remote Restrict search to a stash scope (default: all).
  • --revision:<n> Show a specific stash revision (0 = latest).

Use case ​

Use show-stash to inspect what a stash contains before retrieving it, or to review previous revisions of a stash.

Notes:

  • Always refreshes remote stashes from the server before showing.
  • Prints all operations for the selected stash (or revision).
  • If multiple stashes match the same id, use --scope (and/or --revision) to disambiguate.

Example ​

text
# Show a stash by ID
kscm show-stash --id:1030

# Only search remote stashes
kscm show-stash --id:1030 --scope:remote

# Show revision 1 (oldest) of a stash
kscm show-stash --id:1030 --revision:1

Back to Commands

edit-stash ​

Edit a stash description and access lists.

edit-stash updates the description and/or access lists (owners/viewers) for a stash. You can either replace the entire description, or replace a single tag within the existing description.

Syntax ​

text
kscm edit-stash --id:<number> --description:<text> [options]
kscm edit-stash --id:<number> --replace-tag:<tag> [--tag-value:<value>] [options]

Required options ​

  • --id:<number> Numeric stash ID.
  • --description:<text> New description.
  • --replace-tag:<tag> Replace a tag in the existing description (use without --description).

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --scope:local|remote Restrict search to a stash scope (default: local).
  • --owners:<csv> Owners (usernames, CSV or JSON list).
  • --viewers:<csv> Viewers (usernames, CSV or JSON list).
  • --tag-value:<value> Tag value (omit or empty to remove the tag).

Use case ​

Use edit-stash to update stash metadata without re-stashing files, or to set tags in the description for filters and automation.

Notes:

  • Omitting --owners or --viewers preserves the existing list.
  • Use --owners:[] or --viewers:[] to clear a list.
  • Always refreshes remote stashes from the server before editing remotely.
  • Tag replacement adds the tag if it is missing.
  • If --tag-value is omitted or empty, the tag is removed.

Example ​

text
# Update description and preserve owners/viewers
kscm edit-stash --id:1030 --description:"Updated description"

# Replace or add a tag in the existing description
kscm edit-stash --id:1030 --replace-tag:review --tag-value:alice

# Remove a tag
kscm edit-stash --id:1030 --replace-tag:review

Back to Commands

delete-stash ​

Delete a stash by ID.

Syntax ​

text
kscm delete-stash --id:<number> [options]

Required options ​

  • --id:<number> Numeric stash ID.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --scope:local|remote Restrict search to a stash scope (default: local).

Use case ​

Use delete-stash to remove a stash by ID.

Notes:

  • Always refreshes remote stashes from the server before deleting remotely.

Example ​

text
# Delete a local stash by ID
kscm delete-stash --id:1030

# Delete a remote stash by numeric ID
kscm delete-stash --id:1030 --scope:remote

Back to Commands

retrieve-stash ​

Retrieve a stashed changelist into the workspace.

Syntax ​

text
kscm retrieve-stash --id:<number> --boundcl:replace|new --conflicts:backup|overwrite [options]

Required options ​

  • --id:<number> Numeric stash ID.
  • --boundcl:replace|new How to handle a stash bound to a local changelist.
  • --conflicts:backup|overwrite How to handle local conflicts.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).
  • --scope:all|local|remote Restrict search to a stash scope (default: all).
  • --revision:<guid> Retrieve a specific stash revision by GUID.

Use case ​

Use retrieve-stash to restore work from a stash back into your workspace (for example, after switching machines, after a clean sync, or when recovering from local issues).

Notes:

  • Always refreshes remote stashes from the server before retrieving.
  • If the stash is bound to a local changelist, --boundcl:replace uses it and --boundcl:new creates a new changelist.
  • --conflicts controls what happens when applying a stash would overwrite local workspace changes:
    • --conflicts:backup creates a local backup stash containing your current local changes, then applies the selected stash.
    • --conflicts:overwrite discards your current local changes and applies the selected stash.

Example ​

text
# Retrieve a stash, creating a new changelist if needed, backing up conflicts
kscm retrieve-stash --id:1030 --boundcl:new --conflicts:backup

Back to Commands

submit-changelist ​

Submit a workspace changelist.

Syntax ​

text
kscm submit-changelist --clid:<id> --description:<text> [options]

Required options ​

  • --clid:<id> Workspace changelist id.
  • --description:<text> Description.

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).

Use case ​

Use submit-changelist to publish the operations in a changelist as a new revisions on the server for the files that are part of that changelist.

Example ​

text
cd ~/Dev/MyWorkspace

# Submit a changelist by id
kscm submit-changelist --clid:123 --description:"Fix build warnings"

Back to Commands

submit-files ​

Submit specified files.

Syntax ​

text
kscm submit-files --file:<path> --description:<text> [options]
kscm submit-files --files:<list> --description:<text> [options]

Required options ​

  • --description:<text> Description.
  • --file:<path> Single file path, or
  • --files:<list> File list: JSON (["a","b"]) or CSV (a,b).

Optional options ​

  • --workspace:<name> Workspace name (optional if inferred from the current directory).

Use case ​

Use submit-files to submit new revisions for a specific set of files without explicitly managing a changelist.

Notes:

  • File paths are interpreted relative to the current directory. KSCM resolves them to full paths before processing.

Example ​

text
cd ~/Dev/MyWorkspace

# Submit a single file
kscm submit-files --file:./Source/MyFile.cpp --description:"Quick fix"

# Submit multiple files
kscm submit-files --files:{"./a.txt","./b.txt"} --description:"Batch fix"

Back to Commands

export-skills ​

Export embedded skill files to a directory.

Syntax ​

text
kscm export-skills --destination:<directory>

Required options ​

  • --destination:<directory> Export root directory.

Use case ​

Use export-skills as a quick way to access the skill pack supported by the current KSCM executable. Files are written below <destination>/<skill-name>/; existing skill files are replaced with the version embedded in that executable.

The command does not require authentication or a workspace.

Example ​

text
# Export the skill pack for this KSCM version
kscm export-skills --destination:./.codex/skills

Back to Commands