Shipping the CloudSignal CLI: PKCE Auth, ACLs, and Identity Claims

The decision: a CLI, not an SDK

When we drew up Phase 2 of the platform roadmap, the plan was a TypeScript SDK. A @cloudsignal/sdk package with a CloudSignalClient you import, mirroring the shape of every other vendor library out there. Familiar, easy to scope.

We did not ship that. The week before writing it, we asked what developers actually wanted to do. The answer was: open a terminal, set up a policy, deploy. Nobody wanted to author a Node program to call our API. They wanted a tool.

So we cut the SDK and put the effort into a CLI. The contract changed from “import this client” to npx @cloudsignal/cli. Same surface area, lower friction, no boilerplate to copy from the docs.

Login without paste

The first command is cloudsignal login. The previous authentication story was the standard one: copy an sk_ key from the dashboard, paste it into a .env, hope nobody commits it. That works for one developer on one machine. It stops working the moment teammates rotate in and out of a project, or somebody wants to script CI.

cloudsignal login opens a browser, you sign in with your dashboard account, and the CLI exchanges an OAuth 2.0 authorization code for a short-lived session token. PKCE protects the redirect leg, so the code can only be redeemed by the CLI process that initiated the flow. The token lives under ~/.config/cloudsignal/, scoped per organization, with refresh built in.

No pasting. No long-lived secrets on disk. No environment variable spelunking. If you need to revoke access, you do it from the dashboard and the next CLI command fails closed.

Policies as files

ACL policies are JSON. Treating them as code is the only sane workflow once you have more than one tenant or environment.

cloudsignal acl get > policy.json pulls the current policy into a file you can diff, edit, and commit. cloudsignal acl validate policy.json runs it against the published JSON Schema before any network call, so you catch typos and missing required fields before the server does. cloudsignal acl update policy.json pushes it back.

The fourth command is the one we use most. cloudsignal acl simulate takes a policy and a hypothetical client (organization, identity claims, MQTT topic, publish or subscribe) and tells you whether it would be allowed. It mirrors the broker’s evaluator exactly because both call the same library. You can answer “would this customer’s connection be denied?” without spinning up a connection.

Identity claims, set from the terminal

When we shipped ACL v2 we added {$self} bindings: rules that resolve to the connecting client’s identity at publish and subscribe time. That mechanism is only useful if you can set identity claims on a user. We added that to the CLI too.

cloudsignal user claims set u_abc123 --key org_id --value acme
cloudsignal user claims show u_abc123
cloudsignal user claims unset u_abc123 --key org_id

Claims propagate to broker auth checks immediately. Combined with {$self.org_id} in an ACL rule, you get per-tenant topic isolation without rewriting the policy every time you onboard a tenant. The same workflow that used to require a dashboard click and a manual policy edit now fits in three commands you can put behind a CI step.

What’s next

The CLI is at 0.2.x. The MCP server is Phase 3, and it wraps the same operations so an AI agent in your IDE can manage policies the same way you do. We will write about that separately when it ships.

For now: npm install -g @cloudsignal/cli, then cloudsignal login and you are connected.