Run Claude Code in Scripts and CI Without Interactive Shell

Yes. Claude Code can run without its interactive terminal interface by using its non-interactive, print mode: invoke claude -p with a prompt, then handle the result and exit status in your script or CI job. You still need to install and authenticate the CLI, and you should explicitly control which tools and permissions it can use.

How non-interactive mode works

The -p (or --print) option runs Claude Code with a supplied prompt and prints the response instead of opening the interactive session. This makes it suitable for shell scripts, build pipelines, and other automation that cannot wait for a person to type at a prompt.

A minimal example is:

claude -p "Summarize the changes in this repository"

Run the command from the repository or directory whose files Claude should inspect. For repeatable automation, supply a specific task and decide how your script will consume the output. By default, the response is intended for a person to read; if another program must parse it, request a supported structured output format rather than relying on prose remaining consistent.

Non-interactive does not mean the model runs locally or that the command has no external dependencies. Claude Code still needs a valid way to reach the service and authenticate. It also operates in a filesystem and tool context, so its permitted actions depend on the environment, command options, and configured permissions.

Set up authentication and the environment

Install Claude Code using the currently supported installation instructions for your platform, then confirm that the executable is available to the account running the job. Authentication must be configured before a headless run can succeed. Depending on the account and setup, this may involve an API key or another supported authentication method; check the current Claude Code documentation for the method available to you.

In CI, store credentials in the provider’s secret store and expose them to the job only when needed. Do not put keys directly in a script, repository, command-line argument, or log. Verify that the job’s environment passes the required credential to the process and that the CLI version and configuration are consistent across runs.

• Use a dedicated CI secret rather than a developer’s personal credential when your organization supports that arrangement.
• Restrict which workflows and branches can access the secret, especially for jobs triggered by contributions from outside the trusted repository.
• Keep the working directory and any files Claude needs explicit; a CI checkout may not include the full history or other local files available on a workstation.
• Check the CLI’s exit status and preserve useful diagnostics when a run fails.

Build a reliable script or CI job

A useful automated job separates the prompt, execution, and verification. For example, a review job might ask for a summary of a diff, capture the output, and publish it as a job artifact or pull-request comment. A change-making job should be treated more cautiously: run it on an isolated checkout, inspect the resulting diff, and require the normal review and test process before merging.

set -eu
claude -p "Review the changes in this checkout. Report actionable issues with file and line references. Do not modify files."

This shell example stops if the command returns a nonzero status. In a larger workflow, capture standard output and standard error separately if the CI system needs to display or process them independently. Avoid assuming that every unsuccessful task will produce a particular error message: network problems, invalid credentials, permission restrictions, and task failures can have different causes.

Make prompts bounded and specific. State the directory or files to examine, the desired result, and whether edits are allowed. For tasks that must produce machine-consumable output, use Claude Code’s documented output-format options for the installed version and validate the result before using it. Do not treat generated text as a trusted command or execute it blindly.

Permissions, edits, and safe automation

Automation needs a deliberate permission policy. Claude Code may use tools to inspect files or perform actions, and a workflow can grant or restrict those capabilities. Do not assume that a non-interactive invocation automatically makes an operation safe or that it can safely approve every request without human input. Consult the current CLI help and documentation for the permission and tool-control options supported by your installed version.

For a read-only review, make the task read-only in both the prompt and the configured tool permissions. For a task that edits code, use a disposable or isolated working tree and limit access to what the task requires. Avoid granting access to unrelated secrets, deployment credentials, or sensitive directories. Treat changes as proposals: run tests, inspect the diff, and use your usual review gates.

CI workflows also need protection against untrusted input. A prompt that includes issue text, pull-request content, or repository files can encounter instructions embedded in that material. Keep secrets unavailable to jobs that process untrusted contributions, and do not allow generated instructions to override the workflow’s own controls.

Common problems and useful checks

• The job waits or fails for authentication: confirm the credential is available to the CI process and that the selected authentication method is supported. Check that the job is not running in a context where secrets are intentionally withheld.
• The command is not found: verify installation and the executable’s PATH for the CI user. A tool installed in an interactive shell profile may not be available in a non-interactive job.
• The result differs between runs: make the prompt, checkout, CLI version, and relevant configuration explicit. Model output can vary, so use tests or validation for outcomes that must be deterministic.
• The output is hard to parse: request a documented structured format and validate it; do not extract data from an assumed prose layout.
• The task cannot access expected files: check the job’s working directory and checkout contents, and confirm the requested paths are within the permitted environment.
• The command exits unsuccessfully: preserve stderr and the exit code, then distinguish authentication, network, configuration, and task issues before changing permissions.

When to use the CLI and when not to

Use claude -p when a task can be described in a prompt and completed without interactive follow-up: for example, producing a review summary, explaining a test failure, or proposing a small change in an isolated checkout. It is also useful in scheduled jobs and developer scripts, provided the result is checked appropriately.

Prefer an interactive session when the task needs clarification, when you want to inspect and steer a sequence of actions, or when a human must approve decisions during the work. For stable automation, consider whether the task is better handled by a deterministic script, linter, test, or direct API integration. A model-based response is not a substitute for a test that can precisely verify a required condition.

Frequently Asked Questions

Can Claude Code run without opening its terminal UI?
Yes. Use the print-mode option, claude -p, with a prompt. The CLI still needs to be installed, authenticated, and able to access the required files and tools.

Can I use Claude Code in GitHub Actions or another CI system?
Yes, if the runner can install or access the CLI and provide valid authentication. Store credentials as protected secrets and configure permissions for the job’s trust level.

Does claude -p automatically edit files?
The option selects non-interactive output; it does not by itself define the task or grant every capability. Whether files can be changed depends on the tools and permissions available and the task being run.

Can I get JSON from a headless run?
Use a structured output option documented for your installed Claude Code version, then validate the returned data. Do not assume ordinary prose will follow a fixed schema.

How do I make a CI run fail when Claude Code fails?
Let the shell or CI step propagate the command’s exit status, and configure the job to stop or mark the step failed on a nonzero status. Capture logs so you can diagnose the failure.

Is non-interactive mode suitable for unattended code changes?
It can perform automated tasks when configured to do so, but unattended changes should run in an isolated environment and pass tests, diff review, and the repository’s normal approval gates before they are trusted.

Related

• Funny Siri Commands: 25+ That Actually Work
• Paramount Warner Bros. Merger: What It Means for You
• Reduce Motion Apple Watch: Turn It Off