Profile Commands Reference

This page covers all commands related to Newroz profiles. For general CLI commands, see CLI Commands Reference.

newroz profile

newroz profile <subcommand>

Top-level command for managing profiles. Running newroz profile without a subcommand shows help.

Subcommand	Description
list	List all profiles.
use	Set the active (default) profile.
create	Create a new profile.
describe	Read or set a profile's description (used by the kanban orchestrator for routing).
delete	Delete a profile.
show	Show details about a profile.
alias	Regenerate the shell alias for a profile.
rename	Rename a profile.
export	Export a profile to a tar.gz archive.
import	Import a profile from a tar.gz archive.
install	Install a profile distribution from a git URL or local directory. See Profile Distributions.
update	Re-pull a distribution-managed profile and re-apply its bundle.
info	Show distribution metadata for a profile (origin URL, commit, last update).

newroz profile list

newroz profile list

Lists all profiles. The currently active profile is marked with *.

Example:

$ newroz profile list
  default
* work
  dev
  personal

No options.

newroz profile use

newroz profile use <name>

Sets <name> as the active profile. All subsequent newroz commands (without -p) will use this profile.

Argument	Description
<name>	Profile name to activate. Use default to return to the base profile.

Example:

newroz profile use work
newroz profile use default

newroz profile create

newroz profile create <name> [options]

Creates a new profile.

Argument / Option	Description
<name>	Name for the new profile. Must be a valid directory name (alphanumeric, hyphens, underscores).
--clone	Copy config.yaml, .env, SOUL.md, and skills from the current profile.
--clone-all	Copy everything (config, memories, skills, cron, plugins) from the current profile. Excludes per-profile history: sessions, state.db, backups, state-snapshots, checkpoints.
--clone-from <profile>	Clone config/skills/SOUL from a specific profile instead of the current one. Implies --clone unless paired with --clone-all.
--no-alias	Skip wrapper script creation.
--description "<text>"	One- or two-sentence description of what this profile is good at. Used by the kanban orchestrator to route tasks based on role instead of profile name alone. Skip and add later via newroz profile describe. Persisted in <profile_dir>/profile.yaml.
--no-skills	Create an empty profile with zero bundled skills enabled. Writes a .no-bundled-skills marker into the profile so future newroz update runs won't re-seed the bundled set, and refuses to combine with --clone, --clone-from, or --clone-all (which would copy skills in anyway). Useful for narrow orchestrator profiles or sandbox profiles that should not inherit the full skill catalog. To toggle this on an already-created profile (including the default ~/.newroz), use newroz skills opt-out / newroz skills opt-in.

Creating a profile does not make that profile directory the default project/workspace directory for terminal commands. If you want a profile to start in a specific project, set terminal.cwd in that profile's config.yaml.

Examples:

# Blank profile — needs full setup
newroz profile create mybot

# Clone config only from current profile
newroz profile create work --clone

# Clone everything from current profile
newroz profile create backup --clone-all

# Clone config from a specific profile
newroz profile create work2 --clone-from work

# Clone everything from a specific profile
newroz profile create work2-backup --clone-from work --clone-all

newroz profile describe

newroz profile describe [<name>] [options]

Read or set a profile's description. The description is consumed by the kanban orchestrator to route tasks based on what each profile is good at, rather than guessing from the profile name alone. Persisted in <profile_dir>/profile.yaml so it survives reboots and is shared with the gateway.

With no flags, prints the current description (or (no description set for '<name>') if empty).

Argument / Option	Description
<name>	Profile to describe. Required unless --all --auto is used.
--text "<text>"	Set the description to this exact text (user-authored). Overwrites any existing description.
--auto	Auto-generate a 1-2 sentence description via the auxiliary LLM, based on the profile's installed skills, configured model, and name. Configure the model under auxiliary.profile_describer in config.yaml. Auto-generated descriptions are marked description_auto: true so the dashboard can flag them for review.
--overwrite	With --auto, replace user-authored descriptions too (default: skip profiles whose description was set explicitly).
--all	With --auto, sweep every profile missing a description.

Examples:

# Read the current description
newroz profile describe researcher

# Set it explicitly
newroz profile describe researcher --text "Reads source code and writes findings."

# Let the LLM generate one
newroz profile describe researcher --auto

# Fill in descriptions for every profile that doesn't have one
newroz profile describe --all --auto

newroz profile delete

newroz profile delete <name> [options]

Deletes a profile and removes its shell alias.

Argument / Option	Description
<name>	Profile to delete.
--yes, -y	Skip confirmation prompt.

Example:

newroz profile delete mybot
newroz profile delete mybot --yes

warning

This permanently deletes the profile's entire directory including all config, memories, sessions, and skills. Cannot delete the currently active profile.

newroz profile show

newroz profile show <name>

Displays details about a profile including its home directory, configured model, gateway status, skills count, and configuration file status.

This shows the profile's Newroz home directory, not the terminal working directory. Terminal commands start from terminal.cwd (or the launch directory on the local backend when cwd: ".").

Argument	Description
<name>	Profile to inspect.

Example:

$ newroz profile show work
Profile: work
Path:    ~/.newroz/profiles/work
Model:   anthropic/claude-sonnet-4 (anthropic)
Gateway: stopped
Skills:  12
.env:    exists
SOUL.md: exists
Alias:   ~/.local/bin/work

newroz profile alias

newroz profile alias <name> [options]

Regenerates the shell alias script at ~/.local/bin/<name>. Useful if the alias was accidentally deleted or if you need to update it after moving your Newroz installation.

Argument / Option	Description
<name>	Profile to create/update the alias for.
--remove	Remove the wrapper script instead of creating it.
--name <alias>	Custom alias name (default: profile name).

Example:

newroz profile alias work
# Creates/updates ~/.local/bin/work

newroz profile alias work --name mywork
# Creates ~/.local/bin/mywork

newroz profile alias work --remove
# Removes the wrapper script

newroz profile rename

newroz profile rename <old-name> <new-name>

Renames a profile. Updates the directory and shell alias.

Argument	Description
<old-name>	Current profile name.
<new-name>	New profile name.

Example:

newroz profile rename mybot assistant
# ~/.newroz/profiles/mybot → ~/.newroz/profiles/assistant
# ~/.local/bin/mybot → ~/.local/bin/assistant

newroz profile export

newroz profile export <name> [options]

Exports a profile as a compressed tar.gz archive.

Argument / Option	Description
<name>	Profile to export.
-o, --output <path>	Output file path (default: <name>.tar.gz).

Example:

newroz profile export work
# Creates work.tar.gz in the current directory

newroz profile export work -o ./work-2026-03-29.tar.gz

newroz profile import

newroz profile import <archive> [options]

Imports a profile from a tar.gz archive.

Argument / Option	Description
<archive>	Path to the tar.gz archive to import.
--name <name>	Name for the imported profile (default: inferred from archive).

Example:

newroz profile import ./work-2026-03-29.tar.gz
# Infers profile name from the archive

newroz profile import ./work-2026-03-29.tar.gz --name work-restored

Distribution commands

tip

New to distributions? Start with the Profile Distributions user guide — it covers the why, when, and how with full examples. The sections below are a dry CLI reference for when you know what you want.

Distributions turn a profile into a shareable, versioned artifact published as a git repository. A recipient installs the distribution with a single command and can update it in place later without touching their local memories, sessions, or credentials.

auth.json and .env are never part of a distribution — they stay on the installing user's machine.

The recipient's user data (memories, sessions, auth, their own edits to .env) is always preserved across the initial install and subsequent updates.

info

newroz profile export / import are still the right commands for local backup and restore of a profile on your own machine. Distribution (install / update / info) is a separate concept: ship a profile via git so someone else can install it.

newroz profile install

newroz profile install <source> [--name <name>] [--alias] [--force] [--yes]

Installs a profile distribution from a git URL or a local directory.

Option	Description
<source>	Git URL (github.com/user/repo, https://..., git@..., ssh://, git://) or a local directory containing distribution.yaml at its root.
--name NAME	Override the profile name from the manifest.
--alias	Also create a shell wrapper (e.g. telemetry → newroz -p telemetry).
--force	Overwrite an existing profile of the same name. User data is still preserved.
-y, --yes	Skip the manifest-preview confirmation prompt.

The installer shows the manifest, lists required env vars, and warns about cron jobs before asking for confirmation. Required env vars go into a .env.EXAMPLE file you copy to .env and fill in.

Examples:

# Install from a GitHub repo (shorthand)
newroz profile install github.com/kyle/telemetry-distribution --alias

# Install from a full HTTPS git URL
newroz profile install https://github.com/kyle/telemetry-distribution.git

# Install from SSH
newroz profile install git@github.com:kyle/telemetry-distribution.git

# Install from a local directory during development
newroz profile install ./telemetry/

newroz profile update

newroz profile update <name> [--force-config] [--yes]

Re-clones the distribution from its recorded source and applies updates. Distribution-owned files (SOUL.md, skills/, cron/, mcp.json) are overwritten; user data (memories, sessions, auth, .env) is never touched.

config.yaml is preserved by default to keep your local overrides. Pass --force-config to reset it to the distribution's shipped config.

newroz profile info

newroz profile info <name>

Prints the profile's distribution manifest — name, version, required Newroz version, author, env var requirements, the source URL/path, and the Installed: timestamp recorded when the distribution was last install-ed or update-d. Useful for checking what a shared profile needs before installing it, and for spotting "this profile was installed 6 months ago and hasn't been updated."

newroz profile list also shows the distribution name and version in a Distribution column, and newroz profile show <name> / delete <name> surface the source URL so you can tell at a glance which profiles came from a git repo vs. were created locally.

Private distributions

A private git repository works as a distribution source with no extra configuration — the install shells out to your normal git binary, so whatever authentication your shell is already set up for (SSH key, git credential helper, GitHub CLI's stored HTTPS credentials) applies transparently.

# Uses your SSH key, the same as any other `git clone`
newroz profile install git@github.com:your-org/internal-assistant.git

# Uses your git credential helper
newroz profile install https://github.com/your-org/internal-assistant.git

If a clone prompts for credentials interactively in your terminal during install, that prompt flows through. Set up your auth the way you'd normally use git clone against the same repo first, then install.

Distribution manifest (distribution.yaml)

Every distribution has a distribution.yaml at the root of its repository:

name: telemetry
version: 0.1.0
description: "Compliance monitoring harness"
newroz_requires: ">=0.12.0"
author: "Your Name"
license: "MIT"
env_requires:
  - name: OPENAI_API_KEY
    description: "OpenAI API key"
    required: true
  - name: GRAPHITI_MCP_URL
    description: "Memory graph URL"
    required: false
    default: "http://127.0.0.1:8000/sse"
distribution_owned:   # optional; defaults to SOUL.md, config.yaml,
                      #   mcp.json, skills/, cron/, distribution.yaml
  - SOUL.md
  - skills/compliance/
  - cron/

newroz_requires supports >=, <=, ==, !=, >, <, or a bare version (treated as >=). Install fails with a clear error if the current Newroz version doesn't satisfy the spec.

distribution_owned is optional. If set, only those paths are replaced on update; anything else in the profile stays user-owned. If omitted, the defaults above apply.

Publishing a distribution

Authoring a distribution is just a git push:

1. In your profile directory, create distribution.yaml with at least name and version.
2. Initialize a git repo (or use an existing one) and push to GitHub / GitLab / any host Newroz can clone from.
3. Tell recipients to run newroz profile install <your-repo-url>.

Use git tags for versioned releases — recipients who clone HEAD get your latest state, and you can always bump version: in the manifest.

newroz -p / newroz --profile

newroz -p <name> <command> [options]
newroz --profile <name> <command> [options]

Global flag to run any Newroz command under a specific profile without changing the sticky default. This overrides the active profile for the duration of the command.

Option	Description
-p <name>, --profile <name>	Profile to use for this command.

Examples:

newroz -p work chat -q "Check the server status"
newroz --profile dev gateway start
newroz -p personal skills list
newroz -p work config edit

newroz completion

newroz completion <shell>

Generates shell completion scripts. Includes completions for profile names and profile subcommands.

Argument	Description
<shell>	Shell to generate completions for: bash, zsh, or fish.

Examples:

# Install completions
newroz completion bash >> ~/.bashrc
newroz completion zsh >> ~/.zshrc
newroz completion fish > ~/.config/fish/completions/newroz.fish

# Reload shell
source ~/.bashrc

After installation, tab completion works for:

• newroz profile <TAB> — subcommands (list, use, create, etc.)
• newroz profile use <TAB> — profile names
• newroz -p <TAB> — profile names

See also

• Profiles User Guide
• CLI Commands Reference
• FAQ — Profiles section