Reference
GraphQL and events
Query local Studio state and subscribe to execution updates on the loopback API.
Endpoints
fluentci server --port 6076
GraphQL and GraphiQL are at http://localhost:6076/graphql. Live WebSocket events
use ws://localhost:6076/ws. Studio mode serves the frontend as well; desktop
mode uses a separate OS-assigned loopback port.
This API controls local projects and execution. It is distinct from the public registry's XRPC API and is not a hosted authentication boundary. Keep it scoped to trusted local use.
Query projects
query Projects {
projects(limit: 20) {
id
name
path
}
countProjects
}
curl -sS http://localhost:6076/graphql \
-H 'Content-Type: application/json' \
--data '{"query":"{ projects(limit: 20) { id name path } }"}'
Common queries include actions(projectId: ...), getRuns(projectId: ...),
getRun(id: ...), jobs, job(id: ...), logs(jobId: ...), and full-text
search(query: ...). Project/run pagination supports the arguments exposed by
the schema. Use GraphiQL's introspection for exact input and result types.
Run a project
mutation RunProject($projectId: ID!) {
runPipeline(projectId: $projectId, wait: false) {
id
status
jobs {
id
name
status
}
}
}
wait: false schedules execution and returns the pending run. Query history or
consume events for completion. wait: true waits for execution. Additional
mutations manage projects, save actions, re-run jobs, and cancel runs. Cancellation
status should not be treated as proof that every external side effect was undone.
Identity and suggestions
query LocalIdentity {
currentAccount {
account
did
handle
pds
}
tangledRepositories {
uri
name
cloneUrl
author
knot
}
}
Identity comes from the remembered account file. Repository suggestions come
from the local cache for that account DID. No password or reusable session token
is returned. Other suggestion queries include actionSuggestions,
projectDirectories, and projectNameAvailable.
Live events
The WebSocket sends JSON envelopes with channel and data. Channels include
project, run, job, and log updates:
{
"channel": "job",
"data": { "id": "example", "name": "check", "status": "RUNNING" }
}
The example is an envelope sketch, not a complete job schema. Events supplement
durable GraphQL state. Re-query after reconnecting instead of assuming the socket
replays every missed event. The broadcast implementation can skip lagged updates.
The compatibility field exportActions retains the argument spelling plateform.
Workflow-scoped actions and execution
query Workflows($projectId: ID!) {
workflows(projectId: $projectId) {
id
name
description
enabled
env
path
revision
stepCount
legacy
}
actions(projectId: $projectId, workflowId: "ci") {
name
plugin
commands
enabled
useWasm
env
workingDirectory
}
getRuns(projectId: $projectId, workflowId: "ci") {
id
workflowId
workflowName
status
}
}
createWorkflow takes NewWorkflowInput (id, name, optional description
and copyFrom). updateWorkflow takes WorkflowUpdateInput (name,
description, enabled, env, events, expectedRevision). IDs are immutable.
deleteWorkflow removes a named file while preserving execution history.
Workflow mutations emit a workflow event so connected clients refresh metadata.
Pass workflowId to saveActions, runPipeline, runJob, exportActions,
getRuns, and countRuns to select a workflow. Omitting it selects default
for actions, execution and export, and all workflows for history queries.
saveActions, updateWorkflow and deleteWorkflow accept expectedRevision
to reject stale writes. Use the metadata's revision, or an empty string for a
legacy default that has not yet been written to a file.
WorkflowEventsInput contains optional push/pullRequest filters (branches,
tags, paths arrays), manual, and a schedule array of UTC cron expressions.
PR filters do not support tags. Send null for a disabled event. CI event settings
are metadata only during local execution; runPipeline never evaluates them.
Project Git operations
projectGit(projectId: ID!) returns null outside a Git working tree, or
branch, commit, branches (local branches), upstream, and dirty.
branch is null for a detached HEAD. switchProjectBranch(projectId: ID!, branch: String!) and pullProject(projectId: ID!) return the updated Git state. Switching
accepts an existing local branch; pull requires an upstream and is fast-forward
only. Neither operation forces changes, resets the worktree, or stashes files.
Archived projects and projects with active runs reject mutations. Successful
operations publish project-git with projectId, prompting clients to reload
workflow and module information.