Running Cycle CLI in Pipelines

A pipeline runs cycle-cli with nobody at the keyboard, which changes what authentication has to look like. There is no browser to complete a sign-in, and no desktop session whose credentials the run can inherit. The run supplies its own credentials instead, and those credentials come from a secret store rather than the pipeline file.

This page covers the whole path: choosing a method, creating the credential, wiring it into a run, and rotating it before it expires.

Choosing an authentication method

Where cycle-cli runs	Use	Why
A CI/CD pipeline or build agent	--clientid and --client-credential on the run	Authenticates against the subscription rather than a person, so the credential does not follow one team member's token lifetime.
A scheduled task on a server	--clientid and --client-credential on the run	No browser is available to complete an interactive sign-in.
Any machine, from a token you already hold	cycle-cli auth login --token [arg]	Signs in without a browser and stores the session, so later runs need no credentials of their own.
A workstation where you also use the Cycle UI	cycle-cli auth login	Interactive browser sign-in. Cycle stores the session, so later runs need no credentials of their own.

Client credentials are the better fit for an unattended pipeline, because a token belongs to an individual team member and has to be replaced when it expires. Each of these methods is fully supported.

The deprecated --token parameter authenticates a single run rather than establishing a session. It still works. See Deprecated parameters.

Creating a client and secret

Client credentials are created in the Cycle User Portal, under Application Secrets. A client identifies the application, and its secret is the credential a run presents.

Creating a client

1. Log into the User Portal:
   • Open your web browser and navigate to the Cycle User Portal.
   • Enter your credentials to log in.
2. Access Application Secrets:
   • Locate and click on the Application Secrets option in the user portal.
3. Create a new client:
   • Find the clients section in the left pane.
   • Click the + button next to the clients section.
   • Enter a client name of your choice in the modal that appears, then click OK.

A new client needs authorization before it can authenticate

After creating the client, Cycle Labs still needs to authorize it with the identity provider before you can use it to authenticate with cycle-cli. Email help@cyclelabs.io with your new client name and ID before using it with cycle-cli. Do not send any client secrets in the email.

Generating a client secret

1. Add an application secret:
   • Click the Add Secrets button located in the top right corner of the screen.
2. Name your secret:
   • Enter a name for your application secret in the modal that appears, then press OK.
3. Copy your secret:
   • Use the copy button provided to copy the generated secret.
4. Store your secret securely:
   • Store it in a Key Vault or password manager.
   • Ensure that only authorized personnel have access to it.

The Client ID you pair with this secret is displayed next to the Add Secrets button in user management.

One-time access

This is the only time you will have access to the secret in user management. Copy it before you leave the page.

Authenticating a pipeline run

Pass the client ID and secret on the run itself:

cycle-cli run --clientid $CYCLE_CLIENT_ID --client-credential $CYCLE_CLIENT_SECRET [files to run]

Because no specific user is signed in, Cycle cannot derive a .cycuser file from the identity. Pass -u (--user-profile) to name the file holding the settings the run should use.

Never hard-code a token or a client secret into a pipeline job. Inject it from your secret store as an environment variable:

• In Jenkins, store it as a secret or use the Credentials Plugin.
• In Azure DevOps, store it as a secret variable or in Azure KeyVault.

For a worked Azure DevOps pipeline that authenticates this way and publishes results, see Publishing Reports in CI Pipelines.

Running more than one agent at once

When several Cycle runs can share an agent or a workspace, add --skip-initial-purge so one run does not delete the internal database files another run is still using. See Running cycle-cli in parallel for what the parameter does and why it remains necessary.

Rotating and deleting secrets

Secrets expire, so plan the replacement before the expiration date rather than after a pipeline fails. The Application Secrets list shows a hint of the first three characters of each secret and its expiration date, which is how you identify the right one when several are stored.

To rotate a secret, generate the replacement before removing the one in use, so the pipeline is never left without a working credential:

1. Click + New Secret in the Application Secrets section, name it, and save it.
2. Copy the new secret and replace the stored value in your Key Vault or password manager.
3. Confirm the pipeline runs successfully on the new secret.
4. Delete the old secret: find it in the list, click its delete action, and confirm.

Deleting a secret is irreversible

Any pipeline still using the deleted secret fails to authenticate on its next run. Confirm nothing depends on it first.

Signing in with the auth commands

cycle-cli auth manages the login session. Run it with no sub-command to list what it accepts. For the parameters each sub-command takes, see auth.

Logging in

On a machine with a browser, cycle-cli auth login with no parameters signs in interactively:

cycle-cli auth login
Logged in as j.doe@cyclelabs.io

Cycle stores this session, so a later cycle-cli run on the same machine authenticates without any credential parameters. Cycle refreshes the stored session automatically as long as its refresh token remains valid.

To sign in from a token instead of a browser, which suits a machine with no interactive session:

cycle-cli auth login --token <refresh token>
Logged in as j.doe@cyclelabs.io

Cycle stores this session the same way it stores an interactive one. Copy the token from the Cycle UI first, as described in Obtaining a token.

A login that Cycle cannot complete leaves the machine as it found it:

• An account that is not licensed for Cycle is rejected, and any session already stored on the machine survives untouched.
• A session that cannot be written to the local cache fails the login rather than reporting success. You will not see Logged in as for a login that stored nothing.

auth login also accepts client credentials, which is useful for confirming that a credential works before wiring it into a pipeline. A client-credentials login authenticates the subscription rather than a person, so Cycle stores no session for it. Authenticate the run itself as described in Authenticating a pipeline run.

cycle-cli auth login also reads CYCLE_CLI_CLIENT_ID and CYCLE_CLI_CLIENT_SECRET, but only when both variables are set and none of --client-id, --client-secret, or --token is given. These variables apply to auth login and auth whoami, not to a test run.

The sign-in parameters and the run parameters are spelled differently

auth login takes --client-id and --client-secret. A run takes --clientid and --client-credential.

Diagnosing an agent that will not authenticate

Run cycle-cli auth whoami on the agent first. It reports the identity a run would use, without contacting the authentication service:

cycle-cli auth whoami
Signed in as j.doe@cyclelabs.io
  Token expires:     2026-09-30T14:02:11Z
  Credential source: config file

The credential source is environment variable when CYCLE_CLI_CLIENT_ID and CYCLE_CLI_CLIENT_SECRET are both set, and config file when the identity comes from a stored session. A complete environment credential takes precedence over a stored session. When neither is present, whoami reports Not signed in. An expired stored session is reported as expired rather than as signed out.

Reading the credential source is what separates a missing credential from a rejected one. An agent that reports Not signed in. never received a credential, so check how the pipeline injects the secret. An agent that reports a signed-in identity and still fails is presenting a credential the authentication service rejects, so check that the client is authorized and the secret has not expired.

Because whoami reads only local state, a healthy result does not prove the authentication service accepts the credential.

cycle-cli auth logout clears a stored session when you need the agent to authenticate from scratch.