skills/latchbio-integration/references/operations-and-debugging.md
This reference targets the current stable CLI and SDK (latch==2.76.8).
latch login
latch workspace
Select a known workspace by numeric ID:
latch workspace --id 12345
The active workspace controls unqualified latch:/// paths, Registry access,
workflow registration, and programmatic execution. Surface it before a
destructive or costly action.
Do not read or print ~/.latch/token. Use the CLI's supported login and token
handling.
Basic remote registration:
latch register --yes --open .
Remote builds are the default:
latch register --remote .
Use a local Docker build only when intentional:
latch register --no-remote .
Important options:
# Register into another workspace
latch register --workspace-id 12345 .
# Mark the version as a release
latch register --mark-as-release .
# Register workflows from a non-default Python module
latch register --workflow-module wf.custom_entrypoint .
# Use a specific Dockerfile
latch register --dockerfile Dockerfile.release .
# Plain build output for CI logs
latch register --docker-progress plain .
Registration combines the project version with automatic content/version
information unless disabled. Do not disable automatic versioning merely to
force an overwrite.
A duplicate workflow registration exits with status 2. CI should distinguish
that from status 1, which indicates registration failure.
Before --mark-as-release:
Build an image without publishing a workflow version:
latch register --staging .
Open a remote interactive shell in that image:
latch develop .
Choose a development instance:
latch develop . --instance-size small_gpu_task
Use latch develop --help to inspect the installed version's supported sizes.
.gitignore and .dockerignore are respected.Place small test fixtures under the project root and exclude private or large data from registration archives.
Open an interactive shell for an execution or task:
latch exec --execution-id <execution-id>
For a Nextflow work directory:
latch nextflow attach --execution-id <execution-id>
Use interactive access for diagnosis, not for modifying the source of record. Reproduce and fix the issue locally, then register a new version.
The old latch launch CLI is deprecated. Use
latch_cli.services.launch.launch_v2.
import asyncio
from latch.types import LatchFile
from latch_cli.services.launch.launch_v2 import launch
execution = launch(
wf_name="my_workflow",
version="1.2.3-abcd12",
params={
"reads": LatchFile("latch:///test-data/reads.fastq.gz"),
"minimum_quality": 20,
},
)
completed = asyncio.run(execution.wait())
if completed is None:
raise RuntimeError("execution polling ended without a result")
if completed.status != "SUCCEEDED":
raise RuntimeError(
f"execution {completed.id} ended with {completed.status}"
)
print(completed.output)
print([path.path for path in completed.ingress_data])
wf_name is the registered workflow name (check .latch/workflow_name or the
Console), not the human-readable metadata display name.
launch defaults best_effort=True, allowing compatible dictionaries,
dataclasses, strings for enum values, and other schema-guided conversions.
Set best_effort=False only when the caller imports exactly the same Python
types as the registered workflow.
Compatibility:
import asyncio
from latch_cli.services.launch.launch_v2 import launch_from_launch_plan
execution = launch_from_launch_plan(
wf_name="my_workflow",
version="1.2.3-abcd12",
lp_name="Small public example",
)
completed = asyncio.run(execution.wait())
if completed is None or completed.status != "SUCCEEDED":
raise RuntimeError("launch-plan execution did not succeed")
Execution exposes:
idstatuspoll()wait()abort()Abort only the intended active execution:
if execution.status not in {"SUCCEEDED", "FAILED", "ABORTED"}:
execution.abort()
When Latch MCP is available:
MCP authorization is separate from SDK login. See
references/latch-mcp.md.
Console execution monitoring provides:
The 2.76.8 CLI still provides the following deprecated command:
latch get-executions
The official CLI guide says it will be removed in a future version. Prefer the Console or Latch MCP for new monitoring integrations.
For every production workflow, emit:
message() calls for actionable warnings and errorsDo not log secrets or signed URLs.
latch login
latch workspace
Confirm the workspace is the one containing the data, workflow, and Registry objects. Do not attempt to repair authentication by modifying token files.
wf package.--workflow-module.--docker-progress plain..dockerignore did not omit required files.--no-remote only when the local Docker environment is known-good.latch develop.which python3, installed packages, $PATH, and executable permissions.references/resource-configuration.md.best_effort=True for compatible external representations.